Rationale for choices

[DavidAntaramian]

One of the things I discussed with Christoper earlier via Slack is that I didn't agree with some of the positions taken in the style guide. That's not a criticism of the guide; in fact, I think that the chain of maintainers for this guide has gone to great lengths to ensure that the guide is community driven.

However, I think that the guide can be improved by presenting the rationale of why the guide adopts each particular choice it does. That way, when someone expresses disagreement, they can present a counter-argument to the current choice that can be evaluated by the community. That will make future discussions like #116 easier since the evaluation happens without having to dive through "why was this decision made in the first place; what was the rationale?"

Swinging to the opposite side, I think it would be good to have a note at the top stating that we are presenting a community-reviewed set of options that allow for cohesion and a starting point. I realize that's partially addressed in the "Getting Involved" section, but I just think it would be good for people to see it when they first start reading the guide. We're not intending to create solemn law that must not be violated upon pain of exile. Or as I was telling @christopheradams, this "is more what you call guidelines than actual rules."

[christopheradams]

Here's a rule that differs and so we should consider: always use parens for defs even if they have no arguments.

[DavidAntaramian]

@christopheradams What does it differ with? Just for reference, the same rule is in the lexmag version.

[christopheradams]

@DavidAntaramian the rule in this guide says to omit parens if the def has no arguments.

[DavidAntaramian]

@christopheradams Heh…I clicked on the link you had in your comment thinking it was to this guide. That was my confusion.

I personally always advocate the use of parentheses in named function declarations for reasons of continuity: all the other function declarations that have arguments will have parentheses. I think it also adds to the continuity argument that we also have the following recommendation:

Use parentheses for calls to functions with zero arity, so they can be distinguished from variables.

Therefore, zero-arity function declarations are the anomaly.

Notably the lexmag version has a more relaxed rule for zero-arity calls that restricts its application to local functions:

Parentheses are a must for local zero-arity function calls and definitions

As a paper tiger argument: Omitting them does not substantially change the superficial understanding of what the name means, since the def/defp already indicates the next term will be a function name.

[corroded]

@DavidAntaramian @christopheradams what would be the next course of action for this one? Should we move this clause:

It's our hope that this will become a central hub for community discussion on best practices in Elixir. Feel free to open tickets or send pull requests with improvements. Thanks in advance for your help!

from the Contributing section up top, right below Elixir Style Guide? That way it is more visible. Additionally, moving this clause up as well:

This is community style guide for the Elixir programming language. Please feel free to make pull requests and suggestions, and be a part of Elixir's vibrant community.

would make it clearer that this is community driven and it is more of a starting point.

Lastly, not sure if this is in line with your thoughts, a screenshot of the video @DavidAntaramian posted with the lines The Code is more what you call guidelines, than actual rules... (sort of like a meme) would be helpful - but again depends on where we stand. It could be just a sort of light-hearted (but true!) way of clarifying things. I just fear people might not take it seriously though since it's in meme format?

edit shower thought: no need for images etc. Just a simple:

... the code is more what you'd call "guidelines" than actual rules.

Captain Barbossa, Pirates of the Caribbean: The Curse of the Black Pearl

[christopheradams]

I'm interested in the justification/rationale idea. Here's how I think we can move this forward:

• grep all the rule links and put them on a wiki page, maybe with a checkbox
• check off all the links that have sufficient explanation/justification (for example, the zero arity rule has clear reasons)
• then we can review the list and see where the guide comes up short, and start to improve it

What do you think?

[corroded]

Seems like a good idea. What about styles that are really just that? I mean space and indentation have been argued in all languages over and over so there's no 'proper' justification for it other than it's the preferred style of most people.

[murilobauerc]

I'm interested in the justification/rationale idea. Here's how I think we can move this forward:

• grep all the rule links and put them on a wiki page, maybe with a checkbox
• check off all the links that have sufficient explanation/justification (for example, the zero arity rule has clear reasons)
• then we can review the list and see where the guide comes up short, and start to improve it

What do you think?

Thats seems pretty interesting! Out of curiosity, did we had any progress in this context?

Just bringing this topic alive again because I was curious on the rationale on the naming section about why defguards with boolean checks should be prefixed with is_.

For example, the rationale about the is prefixed on guard clause name:

defguard is_cool(var) when var == "cool"

and here although being a boolean function, is not prefixed with is on the name. Could I name is_cool/1 here?

def cool?(var) do
  String.contains?(var, "cool")
end