I’m falling for a new language many Rubyists may have discovered recently: Elixir.

Word of Elixir seems to have been spreading for a while within the community, especially thanks to Avdi Grimm screencasting about it in his superb series, RubyTapas. Others may have tuned in to the Ruby Rouges’ coverage of it with language creator and Rails Core member José Valim.

Some mucking through my browser history shows that I first heard of it a few months ago in the Status Code email newsletter heralding the release of a new book in the Pragmatic Bookshelf pantheon. I’ll borrow the hook that they wrote, since it seems to have worked on me: Elixir [is] a language built on top of the Erlang VM but that has a more pragmatic, Ruby-esque syntax. I investigated, bought and devoured Programming Elixir in short order.

However, this post isn’t about introducing Elixir, although I hope I’ve supplied some good sources to that end. This also isn’t a discussion about functional programming, learning new languages, or what it is in a syntax that draws me—although those are topics I’d love to visit in the future. This is about summarizing Elixir.

Summarizing Elixir

I’ve been playing around with Elixir; learning its syntax and standard library; and studying its ecosystem, community, and roots (Erlang) for about two months now. I have yet to write anything noteworthy in it, although I’m working on a linear algebra library geared towards distributed computing. (My twin brother does some work for CERN data that inspired me.)

What really intrigues me how a large undertaking in such a language would work. What patterns best compliment the language? Which ones don’t? What’s good applied Elixir style? How does OTP, the Erlang paradigm for constructing fault tolerant applications, work? How does it look in a wild Elixir application? I’m pretty new to functional and concurrent programming, so I have a lot of questions.

Right now, it’s hard to find answers to those questions without dropping down to Erlang, which isn’t where my enthusiasm is at right now. The Elixir ecosystem is young. While there are several great libraries being developed in it, it’s not easy to find open source, serious applications written in it that actually architect solutions complex problems. I wanted more than applied Elixir, I wanted to study the code of someone who’s had to develop with Elixir, attacking the same challenging tasks for months in it.

I started off building a poor man’s Dynamo clone, the Sinatra-style web framework in Elixir, using the bone-fide article for reference when I got stuck. Then something surfaced in the elixir-lang-core mailing list.

The core developers reached a consensus that good documentation style should include a leading paragraph for each module or function, no more than 80 characters long, that concisely summarizes its behaviour. This summary should read well outside of the context of the other paragraphs of documentation, so it can be consumed as a shortdoc in other contexts. It should be written in the active voice, with an implicit subject, and avoid tautological definitions. The diction across summaries should vary enough to prevent tedious repetition when scanning through documentation.

I completely endorse this style, and loathe documents that stray too far from it. The Pareto principle suggests that 80 percent of runtime is spent in 20 percent of the code. What percent of development time is spent knee-deep in reading documentation? We’re all working with each other’s documentation here! More considering the accessibility and psychological ease of consumption of a document can really improve a lot of peoples’ days.

A play in 906 acts

One (excellent) feature of Elixir is that the inline comments in a codebase can be used to generate browseable online documentation through a tool called ex_doc. It’s akin to Ruby’s rdoc (or even more like Python’s epydoc, since both use in-language docstring constructs that Ruby lacks).

It happens that Elixir is 83% written in itself (take that, Rubinius!). The current Elixir documentation frequently employs something similar to the desired style, but not quite. A good portion of it doesn’t fit the bill. The documentation, of course, is inlined with the source code. So implementing this new style of documentation requires that

  • ✔ some poor sap
  • ✔ with a fetish for detail and consistency
  • ✔ who likes overthinking diction
  • ✔ be willing to go through the entirety of Elixir’s source
  • ✔ wanting to make a substantial contribution (at least linewise) to it
  • ✔ without having the experience to be confident in contributing code.

The Elixir source code is the most expansive project developed in Elixir, written by the people who have been attacking complicated problems with Elixir longer than anyone else. There’s no better way to learn its style, conventions, and features, or get ideas for projects that augment it/use it.

I’ve volunteered for the task. Some grepping suggests that there at least 906 public module or function definitions with documentation in the standard library alone. (The same suite of documentation also covers eex, embedding Elixir; ex_unit, testing Elixir; iex, interactive Elixir; and mix, building Elixir.)

By my count, I’m 126 in (Enum was a doozy).

I’m pretty excited about the project. I’m also thankful for the excellent Elixir people, and the opportunity to write some serializable content for this blog. Expect to hear more of my thoughts and observations about Elixir as I make the journey. Wish me luck, and critique my work in progress on GitHub!



I thought I’d launch this blog by introducing a ruby snippet I’ve used in some projects. It’s a convenience method on Object that should look familiar to anyone who’s played around with Object#tap. Object#as is the command to tap’s query, and like tap, its implementation is dead simple.

Continue reading