Fingers over a keyboard and a text editor. This is how most people see our daily routine. Suddenly, no words emerge over the screen. The eyes gaze at the monitor and everything looks static: we’re reading code.

(And we read lots of code).

The reading process demands a huge cognitive effort from us. Once we read a piece of code for the very first time, we’re immersed in a long learning curve and a continuous cycle of questionings, doubts, and insights. Reading code requires us to dig through the mental model of a domain problem and to continuously analyze the input, processing and output flows of some business requirement.

Sure, good developers have been exposed to good writing practices, and there is nothing like reading a clean, robust and elegant piece of code. Our methods are small and expressive and intend to reveal interfaces.

Nevertheless, we still must read them line by line, and gradually lay down our understanding about it.

(“Only well written and tested code is not enough to connect the dots…”, some wise person may have already said this before.)

A large number of whiteboard discussions may have been lost, merely because there was no room for those. Commit messages were laconic and our memorization skills were overestimated. Yesterday’s obvious is now a mine of untangled knowledge.

Furthermore, the practice of comment about code is often discouraged. After all, we prioritize working software over overwhelming documentation. We’re agile developers and we cannot afford the maintenance burden. Code comments are mostly faced as the inability to express oneself in a clever way, and the activity of documenting code is usually associated with redundant, undesired and ungrateful comments.

But here it goes: the key point on documenting is maintaining information that resists as time goes by.

A practical example

Suppose our sample application deals with a concept of contracted plans on its domain, where each plan offers a storage limit in a remote storage service. One of the requirements is to present a summary of a contracted plan’s consumption, as shown in the example below:

'2.44% (500 MB of 20 GB)' # User has consumed 2.44% from a 20 gigabytes
                          # storage limit (i.e., 500 megabytes).

Our source data is a domain object ContractedPlan, which exposes two main pieces of information: the storage limit value (in the plan_storage_limit column) and the total consumed (in the total_consumed column) until the present moment, both persisted in numeric bytes in the database.

The consumption summary must present these two pieces of information, in addition to the percentage of how much has been consumed until now:

\> contracted_plan = ContractedPlan.last

\> contracted_plan.plan_storage_limit # Client has contracted a 20 GB plan.
# => 20_000_000_000

\> contracted_plan.total_consumed # User has consumed 500 megabytes until now.
# => 500_000_000

The percentage of how much has been consumed can be calculated simply applying the following statement:

\> total_consumed_in_percent =
  (total_consumed * 100.to_f / total_contracted).round(2)
# => 2.44

Knowing that such summary statement must be rendered in an HTML page, we’re gonna create a ContractedPlansHelper#plan_consumption_summary helper with the following implementation:

module ContractedPlansHelper
  def plan_consumption_summary(contracted_plan)
    total_contracted = contracted_plan.plan_storage_limit
    total_consumed = contracted_plan.total_consumed
    total_consumed_in_percent =
      (total_consumed * 100.to_f / total_contracted).round(2)

    format(
      '%s%% (%s de %s)',
      total_consumed_in_percent,
      number_to_human_size(total_consumed, precision: 4),
      number_to_human_size(total_contracted)
    )
  end
end

The #plan_consumption_summary method has a structure divided into two main parts: data preparation and data presentation (including the step for formatting the three expected pieces of information).
Even though it looks like a simple and straight logic, there are some points not so obvious for newcomers to that code. The data presentation part depends on a moderately complex structure, in a way that is not an easy piece to digest regarding the “shape” of the returned String (i.e., the syntax of the format method, besides the two calls for the #number_to_human_size method).

There are, of course, some ways to find out how the returned text will be printed out:

• Reading the unit tests;
• Opening the page that uses that helper on the web browser; or
• Executing the helper on the application console (rails console).

All alternatives, however, requires the reader to make an additional effort. All of them encourage the reader to leave out its current context, which is reading the application code in the text editor. In that case, we can leverage code documentation as a technique to facilitate the expected understanding.

First of all, the plan_consumption_summary method can provide a simple usage example, with real data expected from business customers:

# plan_consumption_summary(contracted_plan)
# # => '2.44% (500 MB of 20 GB)'
def plan_consumption_summary(contracted_plan)
  total_contracted = contracted_plan.plan_storage_limit
  total_consumed = contracted_plan.total_consumed
  # ...

The first goal was accomplished. We have diminished the learning barrier to the method logic, without breaking the flow of reading code. Moreover, by being exposed to real data examples, we had a better understanding of some concepts present in the application domain, at a very low cost.

The next snippet that we may add is a title that describes briefly what is the method in that case. Let’s think for a moment. How would we describe the plan_consumption_summary to someone who has just joined the project?

A possible dialog could be:

Well, this method returns a summary of how much a user has consumed in a certain plan.

Bringing the same information to the code, we have this:

# A summary of how much some user has consumed in a certain plan.
#
# plan_consumption_summary(contracted_plan)
# # => '2.44% (500 MB of 20 GB)'
def plan_consumption_summary(contracted_plan)
  total_contracted = contracted_plan.plan_storage_limit
  total_consumed = contracted_plan.total_consumed
  # ...

By describing the title of a method, we have the chance to reflect and identify whatever noise is between a concept and its implementation. The mere act of writing documentation helps us to give remarkable names to our objects, methods, and variables. If the previously written code has been derived only from what was talked or listened, now we have a third communication channel.

At this moment, our documentation has two pieces of information with different semantics: a title and an example. We can apply to it a bit of hierarchy, (i.e., setting apart free text and code), we can make this structure a bit more evident:

# A summary of how much some user has consumed in a certain plan.
#
# Examples
#   plan_consumption_summary(contracted_plan)
#   # => '2.44% (500 MB of 20 GB)'
def plan_consumption_summary(contracted_plan)
  total_contracted = contracted_plan.plan_storage_limit
  total_consumed = contracted_plan.total_consumed
  # ...

We can also add up a piece of information that points out that the method has a public visibility and, therefore, can be used by outside application code (i.e., the view layer). In our example, we use the Public: keyword:

# Public: A summary of how much some user has consumed in a certain plan.
#
# Examples
#   plan_consumption_summary(contracted_plan)
#   # => '2.44% (500 MB of 20 GB)'
def plan_consumption_summary(contracted_plan)
  total_contracted = contracted_plan.plan_storage_limit
  total_consumed = contracted_plan.total_consumed
  # ...

The third point that we can cover is about the type/shape of data that will be returned from the method. Since we know that the return type will be a String, we can add such information with Returns a String:

# Public: A summary of how much some user has consumed in a certain plan.
#
# Examples
#   plan_consumption_summary(contracted_plan)
#   # => '2.44% (500 MB of 20 GB)'
#
# Returns a String.
def plan_consumption_summary(contracted_plan)
  total_contracted = contracted_plan.plan_storage_limit
  total_consumed = contracted_plan.total_consumed
  # ...

In order to complete the input-processing-output triad, we also describe the expected input data, along with a brief description of each snippet. Our case is simple, as we just want an instance of ContractedPlan model, and there is no other primitive values involved.

# Public: A summary of how much some user has consumed in a certain plan.
#
# contracted_plan - A ContractedPlan instance.
#
# Examples
#   plan_consumption_summary(contracted_plan)
#   # => '2.44% (500 MB of 20 GB)'
#
# Returns a String.
def plan_consumption_summary(contracted_plan)
  total_contracted = contracted_plan.plan_storage_limit
  total_consumed = contracted_plan.total_consumed
  # ...

We have now a basic backbone of code documentation. We know how to answer the “what’s” and “how’s” intrinsic to the #plan_consumption_summary method. We can finally include another significant piece of information, one that is mostly unfeasible to describe using just the programming language lexicon: the context.

We know context is everything. Unfortunately, there is information that might be lost in time, especially after some cycles of team rotation and turnovers. The context can help us out to surface the aspects of “when to use a method” and “the reason/intentions behind using this”.

In our example, we can describe something that conveys the following message:

The plan_consumption_summary method is important so that users have access to what has already been consumed by them (since they could run out of storage space), and it can be used on pages that present data on plan consumption.

Assuming that such information is relevant, we can include it on the code documentation:

# Public: A summary of how much some user has consumed in a certain plan.
#
# This can be used whenever the information about a contracted plan is
# presented to the its user. This way, they can get a quick overview
# regarding the current state of the plan usage.
#
# contracted_plan - A ContractedPlan instance.
#
# Examples
#
#   plan_consumption_summary(contracted_plan)
#   # => '2.44% (500 MB of 20 GB)'
#
# Returns a String.
def plan_consumption_summary(contracted_plan)
  total_contracted = contracted_plan.plan_storage_limit
  total_consumed = contracted_plan.total_consumed
  # ...

We can consider the job done now.

It is then a good time to notice that the format used in our example was not conceived by my free will. Attentive readers may have perceived that we used the TomDoc format, created by Tom Preston-Werner. The TomDoc spec aims for simplicity and clarity of communication and it is hugely used in GitHub projects (and here at Plataformatec as well).

Conclusion

An important goal of writing code documentation is to provide an initial context to facilitate and foster the understanding of a piece of code. It’s an empathetic tool that provides a rough, overall idea of the code, even before “one starts reading the code”. By using it wisely, the reader can get a glimpse of what will be executed by the language interpreter/compiler, with little effort.

Code documentation is, of course, only one of many other artifacts that are at our disposal, in order to keep the knowledge base of a software system alive. I consider that as important as having well-described commit messages, README files, project wikis, architectural decision records, BDD specification. etc. They all work together focused on the same essential goal: empower developers to write better software.

The post The anatomy of code documentation first appeared on Plataformatec Blog.

Pattern matching

Imagine you have a string with format foo=bar&token=value&bar=baz where you want to extract the value for the key token which may appear anywhere or not at all in the string.

Here is one solution a developer not very-acquainted with pattern matching would try:

def get_token(string) do
  parts = String.split(string, "&")
  Enum.find_value(parts, fn pair ->
    key_value = String.split(pair, "=")
    Enum.at(key_value, 0) == "token" && Enum.at(key_value, 1)
  end)
end

At first the code seems to work fine but once we go deeper we can see it makes many assumptions we have not really planned for!

For example, what happens if someone passes "foo=bar&token=some=value&bar=baz" as argument? The code will work and will return the string "some". But is that what we really want? Maybe we wanted "some=value" instead? Or maybe we wanted to reject it all together?

There are other examples where the code above would work by accident, possibly adding complexity to the codebase as other users may start to rely on such behaviour.

The most idiomatic way of writing the code above in Elixir is by using pattern matching:

def get_token(string) do
  parts = String.split(string, "&")
  Enum.find_value(parts, fn pair ->
    [key, value] = String.split(pair, "=")
    key == "token" && value
  end)
end

With pattern matching, we are asserting that String.split/2 is going to return a list with two elements. If someone passes "foo=bar&token&bar=baz", it will crash as the list will have only one element. If someone passes "token=some=value", it will crash too as it contains 3 items.

Our new code does not contain any of the accidental complexity of the previous one and it will also be faster. Any input that does not match the given pattern will lead to a crash, giving us the perfect opportunity to discuss and decide how to handle those corner cases.

Polymorphism is opt-in

Elixir provides protocols as a mechanism for polymorphism. A protocol allows developers to express they are willing to work with any data type, as long as it implements the protocols X, Y and Z.

I have previously compared Elixir protocols to alternatives in languages like Swift and Ruby. One nice aspect of Elixir protocols is that they are explicit, you need to explicitly outline and define a protocol for data structures to implement.

For example, one protocol in Elixir is the String.Chars protocol, which converts any data type to a string, if that data type can be converted to a human-readable string. The to_string function uses such protocol for conversions:

iex> to_string("hello")
"hello"
iex> to_string(1)
"1"
iex> to_string URI.parse("/")
"/"
iex> to_string %{hello: :world}
** (Protocol.UndefinedError) protocol String.Chars not implemented for %{hello: :world}

Imagine you have a function that converts underscores to dashes in a string:

def dasherize(string), do: String.replace(string, "_", "-")

Now imagine that at some point you decide to call to_string/1 before calling replace/3:

def dasherize(data), do: String.replace(to_string(data), "_", "-")

Albeit small, this is a drastic change to our code. Our dasherize function went from supporting only strings as argument to support a large number of data types. In other words, our code became less assertive and more generic.

That said, before adding protocols to our code, we should ask if we really intend to open our function to all types. Maybe we want dasherize to support only atoms and strings? If so, we should rather write:

def dasherize(data) when is_atom(data), do: dasherize(Atom.to_string(data))
def dasherize(data), do: String.replace(data, "_", "-")

However, if we are confident we want a protocol, then we should indeed use the protocol and write a test case that guarantees our function works for at least a couple types that implement such protocol. Such tests are extremely important to guarantee we don’t make a different assumption somewhere in the same function.

Note this trade-off does not only happen in protocols, but in any polymorphic API, like the Dict module. In practice, one should rather use specific dict implementations, like the Keyword and Map modules, and rely on the Dict module only when polymorphism is desired.

Map/struct access

Elixir provides maps, known as dictionaries in other languages, as a key-value data structure. Maps are created as follows:

map = %{name: "john", age: 42}

Maps allow two types of access. A strict access, that requires the field name to exist in the map, and a dynamic access, that returns nil if the field does not exist in the map:

# Strict access
iex> map.name
"john"
iex> map.address
** (KeyError) key :address not found in: %{age: 42, name: "john"}

# Dynamic access
iex> map[:name]
"john"
iex> map[:address]
nil

Both syntaxes have their use cases but we should prefer the strict syntax when possible as it helps us find bugs early on. The same applies to structs, which are named maps:

defmodule User do
  defstruct [:first_name, :last_name, :age]

  def name(user) do
    "#{user.first_name} #{user.last_name}"
  end
end

User.name %User{first_name: "John", last_name: "Doe"}
#=> "John Doe"

In the example above, we have defined a User struct and a name/1 function that receives the struct and returns its name. Since we are using user.first_name, if we accidentally pass a struct that does not contain such a field, it will crash immediately, with a nice error message!

In fact, the strict aspect of the user.first_name syntax is one of the reasons why structs do not support the dynamic syntax out of the box:

user = %User{first_name: "John", last_name: "Doe"}
user[:first_name]
** (Protocol.UndefinedError) protocol Access not implemented for %User{...}

In case you want to use the dynamic syntax, you need to derive the Access protocol for the User struct:

defmodule User do
  @derive [Access]
  defstruct [:first_name, :last_name, :age]

  def name(user) do
    "#{user.first_name} #{user.last_name}"
  end
end

However, only derive Access when you truly need to do so, as it is much better to push yourself to rely more on the strict syntax. I would even say relying on Access for structured data is an anti-pattern itself!

Wrapping up

The most interesting aspect of all examples above is that writing in the assertive style leads to faster, more concise and maintainable code. Even more, it allows us to focus on specific scenarios, postponing any complexity (incidental or accidental) to only when we need them, if we need them.

The post Writing assertive code with Elixir first appeared on Plataformatec Blog.