Communicating Intent through Idiom and Paradigm Selection

Making code more readable and more explicit? Reg Braithwaite believes that correctly choosing programming idioms can be instrumental for achieving that goal. He stresses that there are often several ways to get to the desired outcome and the choice should not be random. One should prefer the tool that signals in a most obvious way the intent of the piece of code that is being built. Syntax choices, for instance, can bear useful information about code’s intent:

Consider blocks in Ruby. Some people use do … end when the block needs multiple lines and { … } when it fits on one line. A popular (AFAIK) and superior idea is to use do..end and {…} to disambiguate between blocks that are executed chiefly for their side effects and blocks that are executed for their return values:

foo.map { |x|
# I care about the result
}
foo.each do |x|
# I care about the side effects
end

The computer doesn’t care, of course, but it signals an extra piece of information, the fact that you are chiefly interested in side effects in one case and chiefly interested in the result in another case.

Braithwaite believes that this approach is not limited to syntax idioms but can scale up to paradigms. In some languages, e.g. Ruby, “there are several entirely different philosophies the language supports.” This can be used as a means to declare intent by borrowing idioms from paradigms that correspond the best to what one is trying to achieve.

By making functional things look functional, you clearly signal that you are performing a calculation strictly for the result. Using imperative syntax like for and while should be reserved for the times you need to mutate variables or cause other side effects. […] Likewise, OO is a great paradigm—when you are modelling entities in the real world or when you need long-term persistent state. Languages like Ruby force you to use objects behind the scenes, your code shouldn’t look OO unless you are trying to signal your colleagues that there are entities involved.

Even though it is obvious that, sometimes, the choice of paradigm may be imposed by performance requirements, using this kind of conventions, when possible, allows providing additional information to programmers thus making code more readable and more expressive.

Some argue that using undocumented and unvalidated conventions would only result in more confusion. Reg argues, however, that any project involves programming conventions of some kind, e.g “using Bang! method names to indicate state changes (sort vs. sort!)”, and that nothing prevents teams from documenting established conventions, if necessary.

What do you think about using idioms as signals and means to declare intent?