Learn more here: Open Inaka
Brujo Benavides is a staff engineer that works with Erlang at NextRoll. He also maintains various open source erlang projects. You can learn more about him on his about.me here. He is a member of the inaka community, authors of the erlang_guidelines repository and Elvis, among many other open-source projects.
For erlang_guidelines, is it just documentation or does it have the functionality to apply to the code? Or that Is the purpose of elvis?
It’s just documentation. It has some code (every rule has some examples of good and bad code). That code does compile and it’s generally, at least syntactically, correct. But the main purpose of the repo is to provide documentation on good practices to follow when writing Erlang code.
The actual code that validates some of the rules is in Elvis, indeed. More on that in the next answer 😉
How are erlang_guidelines and elvis related?
We created the Erlang Guidelines repo to put an end to the endless discussions in pull requests that we used to have. When we were a team of 3 or 4 devs, all working in the same office, agreeing on the proper ways of writing Erlang code was… let’s say… simpler. But as we started to grow and work remotely, all that shared knowledge was suddenly spread out across the team and it was only shared on pull requests and other code reviews. That meant that the good practices that were enforced depended a lot on who was writing the code and who was reviewing it. In turn, that led to some projects having wildly different parts that were only consistent among themselves, but not as a whole.
We quickly realized that we needed to have a place where to collectively decide how we wanted to write code as a company. And that’s how erlang_guidelines came to be. It’s a collection of all the rules that we generally enforced in our Erlang codebases, properly organized and with the reasoning behind each rule.
When we started, we thought that it was going to have… maybe… 20 rules? 30 tops!
Well, we were in for a huge surprise.
In a few months we had collected more than 60 rules, and we kept collecting them as time went by.
At some point we realized that we couldn’t possibly validate all the rules by hand on all the pull requests. We needed an automated tool to do that.
Ruby developers had Hound, so… we created Elvis (“you’re nothing but a hound dog…”, you know).
Elvis codifies and automates the process of validating as many of our guidelines as we could conceivably encode. Some rules (like use the same variable name for the same thing across all your codebase) are simply too hard (or even impossible) to codify. Those must still be validated by hand. But for the other ones (e.g. use spaces, not tabs), there is Elvis!
Why did Inaka decide to put out a set of programming guidelines for erlang to supplement the official documentation? Should other programming languages follow suit?
Well… The official documentation was poorer than it is today back then. And even today, it speaks little about code style and guidelines. So, just follow the official guidelines was and still is not even close to enough for us. It just leaves too much room open for interpretation and creativity. For other languages, there are community-approved guidelines in a centralized repository, often sanctioned by the language maintainers themselves. Would we love for the Erlang/OTP to sanction our guidelines as the official guidelines for the whole community? YES, VERY MUCH YES! Will that happen anytime soon? Definitely not. But that’s fine. They’re still the most used unofficial guidelines for the Erlang community. It’s something 😉
In a nutshell, how does elvis (erlang linter) work?
Elvis is a static analyzer that works on a per-module basis. It picks up the code for a module, gets its AST (abstract syntax tree) and runs a long list of rules over it. Each rule is independent, it has its own configuration, and it may produce its own warnings. Finally, all the warnings are collected and printed out in a clear way (In an even clearer way if, instead of using elvis -the shell script-, you call Elvis through the rebar3_lint plugin, that I also maintain). You can even create and add your own rules via a simple configuration file, called elvis.config. Developers usually add this command to their CI pipelines and so it prevents bad code from being merged in the main version of their applications.
Are there any automated documentation tools (that you’d recommend) for erlang and elixir?
I don’t know of any automated documentation, but… I’m also the maintainer of one automated specification writing tool: rebar3_typer ( https://github.com/AdRoll/rebar3_typer/ ). It’s yet another rebar3 plugin that can add specifications to all for your functions automatically.
If you were to change anything about Erlang Ecosystem Foundation documentation and erlang.org documentation what would it be?
I don’t know if I would change anything in particular. The Erlang/OTP team is doing a great job focusing on developer satisfaction during these last few years. Part of it includes a lot of progress to make documentation more accessible and understandable. We still have a very long road ahead, but I wouldn’t personally request anything in particular.
What would you do to improve erlang_guidelines, can anyone contribute to this project on GitHub?
What I would love (other than the guidelines being officialized by the OTP Team or the EEF) is for the repo to eventually be turned into a website where people can inspect the guidelines more dynamically and interactively. But that requires quite a lot of time and expertise, and I don’t have any of those 😛
Regarding contributions: YES!! Everybody can contribute… If anybody wants to promote a rule, they can open an issue (the only requirement is for the rule to have a Reasoning and Examples of good and bad practices). If anybody wants to demote a rule, they can also open an issue (this time the only requirement is the reasoning). If said issues gather enough votes… I’ll happily turn them into pull requests and, once reviewed by the other inakos, merge them into the guidelines.
If you were to design your own automated documentation system for erlang, what would that look like and its functionality be?
I’m actually not sure about this. The only thing that comes to mind would be to add doctests, like the ones Elixir has. With them you can include code in your documentation (as examples) and it gets evaluated and run so that you’re sure that it’s still working after you made changes to the production code. It’s a really really nice feature.
Big thanks to Brujo Benavides.
The Bitsource 
Leave a Reply