The Elixir Style Guide

I was recently asked to step up and become the maintainer for the Elixir Style Guide. It was, I believe, the first, and is now the most popular, community-driven style guide for Elixir.

The guide aims to be very accessible and open to contributions, and if you’re willing to send us your changes and feedback, it’s a great way to give back to the Elixir community that has given us so much.

As the guide says:

Style matters. Elixir has plenty of style but like all languages it can be stifled. Don’t stifle the style.

If you have a little time please check the open issues and pull requests, and leave a comment or question. Looking forward to hearing from you!

8 Likes

How about merge this guide with: Credo’s Elixir Style Guide and add issue to Credo github project?

3 Likes

+1 on merging with Credo, that way we’ll have sane defaults and suggestions out of the box if we use Credo (just like Elm did with elm-format, while not exactly a linter).

Well, unless if that’ll make the styleguide less “by community”.

1 Like

Originally the suggestion might have gone the other way around. The Elixir Style Guide has quite a few more rules/ideas than the one for Credo, and it’s not clear they would all fit in there, as a “personal style guide.”

But there’s no reason we shouldn’t work together and share ideas and benefits.

It would be better if we merge them and ping @josevalim to approve as “Official Elixir Style Guide”. In atom-beautify is issue to Add support for Elixir #545. It would be much more easier to maintain support (also for Credo project) for official style guide instead of multiple style guides that could conflict now or in future. How to fix conflicting rules if we don’t have official approve? So it could be going to solve possible conflicts in different way for each project that depend on it and this may cause problems especially for Elixir beginners.

1 Like

As a word of caution, I wouldn’t hold out for an “official” style guide or expect that the core team would want to maintain this kind of thing.

But it would be great if someone would detail where the style guides diverge. We also shouldn’t be quick to dismiss a plurality of styles.

@lexmag, from Elixir, maintains a style guide mostly aligned with Elixir source: https://github.com/lexmag/elixir-style-guide. If we are ever going to adopt something as official, which is unlikely, that one is the most likely.

10 Likes

Thanks for weighing in @josevalim. The style guide from @lexmag is also really great. I’m not sure anyone wants to settle on one thing at this point. My feeling is that any “official” guide would focus on the minimal set of conventions, whereas the style guide I linked to can afford to be both broader and more detailed.

But I also get that a lot of users want something simple and easy to apply, which is where Credo maybe comes in.

1 Like

@josevalim: Nice to see that we already have a style guide that is accepted by core developers! Of course merging @christopheradams style guide and Credo style guide at now is not needed.
Last thing is to ask if @lexmag and/or other contributors are looked at other style guides and express opinion about possible differences between them and @lexmag version. There is a possibility that in the other style guides appear rules and/or exceptions for existing rules that could/should be accepted.

1 Like

Having tried go before, I’d just really like to leave my 2 cents here:

Go imposes a style guide, which I found a bit awkward at the beginning but then grew in me as I found it very liberating. Style is one of those things that’s a bit pointless to discuss, any sensible option is more than good enough.

Anyways, forcing a style does have quite a few good things, especially if it comes:

  • No pointless discussions about what one should use.
  • Every repo is just like your own code.
  • You can easily automate it.

I do agree with @christopheradams, if an official style guide is enforced (and the tools to do so are built) it needs to be something minimal and to the point rather than a complete style guide.

3 Likes

For some things it can clearly be seen that one kind of writing will be less error-prone than another.

But in many other cases, the exact method used is not as important as that you (and your team) are consistent: Things like tabs vs. spaces, order of pattern-matching in parameters (x = %{} or %{} = x?), names given to exception classes, et al. I really like Credo’s approach of saying “It doesn’t matter which one you like best, but pick one and stick with it”.

I think it is great that we have multiple style guides, because this means that people will stay conscious about the choices w.r.t style they make.

I think that right now we do not need an officially endorsed (or enforced) style guide, because Elixir’s syntax itself is already a great tool to help developers write reasonably readable and consistent code.

4 Likes

There are two ways to look at it from individual standpoint you are absolutely right, but from standpoint of a large organization go approach is way more preferable IMHO.

Since Credo was mentioned, I’m not aware of anything in the Elixir Style Guide that contradicts it. (We might however be missing a few rules that we should fill in.) I think you should be able to follow any of the style guides and get Credo’s linter to pass.

However, we also have some guidelines that will probably never make it into a linter, such as how to organize your module attributes/directives.

As long as you’re enjoying Elixir and sticking to a style you’re doing well!

4 Likes

For those looking to contribute to the Elixir Style Guide, now is a great time. We’ve marked some Help Wanted issues.

Most of these have a solution proposed that would probably be quickly reviewed/accepted. Of course all other submissions are welcome!

We now have the Elixir Style Guide translated into three languages!

2 Likes

The Elixir Style Guide has two new translations:

The Spanish translation is pretty complete and up to date, while the Portuguese one has just gotten started.

I’m sure both would be open to your contributions if you’re knowledgeable in one of these languages!

3 Likes