Request For Coments / Best Current Practice

[Petre Damoc]

I propose that we have an explicit RFC style mechanism that should distill the best practices in Elm programming.

A BCP for Style Guide for Elm source code could be a prime candidate.

A BCP for folder structure and elm-package.json details of a project could be another useful document

The Collective Code Construction Contract could be another BCP.

[Ryan Rempel]

This could, I think, fit with the 'Guides' mandate here.

I suppose my one hesitation would be something like this. Part of the method of @elm-community (as a Github organization) is to be unofficial. There is, after all, @elm-lang for official things.

So, I wouldn't want @elm-community to become too focused on sorting out the "best" from the "very good", if you know what I mean.

But, that does leave lots of room for documenting successful practices. I suppose I would just want to leave room for the idea that there could be more than one successful practice in some areas.

[Petre Damoc]

I understand your concerns and I fully agree. Normally, this kind of effort would be in @elm-lang next to projects like elm-format.

I was thinking that maybe elm-community could be the vanguard of Elm, exploring new territory.

[Ryan Rempel]

I do think the "vanguard" idea fits -- it's one of the advantages of being unofficial -- you can experiment a bit more if the stakes aren't as high as they are for the official project.

I guess the other question is what, tangibly, we need to do to start collecting BCP's. Would you see it as being a wiki? Or individual repositories? Or one repository with sub-folders? Or something else? We also have the elm-faq repository now, which presents a different kind of UI.

My own instinct is to start small and see how things go, but I'm not sure what tangible answer that leads to in this case :-)

[Fred Yankowski]

If elm-faq should restructured to some other UI I'm fine with that. Carrying over the github-pages / jekyll format was the easy way to start.

[Petre Damoc]

I think that Requests For Comments style documents might be the most appropriate.

It makes for an easier and more search friendly shortcut... like PEP-8 or PEP-20 are for Python.

Maybe find some Elm specific memorable three-letter-acronym like ECO (Elm Community Outline). The idea being that ECO is a document produced by the Elm Community that Outlines some best practice. :)

[Ryan Rempel]

I think elm-faq is good as it is -- it's a very pleasing UI for shorter, more focused topics. Whereas the ECOs would tend to be longer documents.

So, what I'm tentatively thinking is that we might create a repository for ECOs, and then we can work out what the documents look like and how they get presented / organized. For instance, at first they might be in markdown format, so Github would basically render them. Then, once we have a few, we could think about how best to present them.

I guess the main alternative would be to use Github's wiki feature -- I don't really have any experience with that, so I'm not sure what kind of advantages / disadvantages it has over plain-old-files-in-a-repository.

[Max Goldstein]

At least when starting out, we could keep ECOs in a folder in this repo. But even that seems to be putting the cart before the horse -- let's try out a few community guidelines or discussions and see what we can learn in order to distill a formal process. We might not need one.

I do think that a style guide would be a good thing. The official one is incomplete, [Laszlo's-(https://gist.github.com/laszlopandy/c3bf56b6f87f71303c9f) is out of date, and NoRedInk's addresses only a few reasonable cases.

Although I didn't at first, I really like the "bring things down a line" convention. It makes the code feel more intentional and less dependent on how long the previous line was. I disagree with the blank lines in case expressions, and I think one blank line is enough between top-level definitions. Having more vertically compact code means more code

And there are a few things, like record updates, that I'm not entirely sure what's the best way.

Maybe we should start compiling all the ways to format a particular piece of syntax and then choose which way is best. Although, in actually doing that, it quickly became clear what was the best version.

-- syntax at end of line, spaces around braces
{ particle |
  position = particle.position + particle.velocity,
  velocity = particle.velocity + particle.acceleration }

-- syntax at end of line, except } is brought down, makes you want trailing commas
{ particle |
  position = particle.position + particle.velocity,
  velocity = particle.velocity + particle.acceleration
}

-- syntax at start of line, indented two spaces, using | for first item only is meh
{ particle
  | position = particle.position + particle.velocity
  , velocity = particle.velocity + particle.acceleration
}

I think the ideal would be the second one with a trailing comma, but until that's added, the first is a reasonable alternative. The third looks odd but not horrible, so I've added it to see what people think.

Also, this is purely aesthetic, not based on a principle like minimizing diff noise, although that's exactly what the ideal version does.

But back to process, we could put up a markdown document wiki page so everyone can edit (or several, one per syntax piece?) and let people edit them. If there are real disagreements, we'll discuss, but I think that in the process of writing down different style we'll gravitate towards something. I can set this up if people like. Sorry for the tangent.

[Noah]

Closing due to stale issue