A big part of being a programmer is describing code to peers. However, describing the abstract and formalized code constructs in natural language is not always an easy task. This article highlights some techniques that help communicating code to peer programmers. The focus is on communicating the code “itself” instead of through its behavior, which is a whole different topic.
Design Patterns
A design pattern names, abstracts and identifies the key aspects of a common design structure that make it useful for creating a reusable object-oriented design.
“Design Patterns – Elements of Reusable Object-Oriented Software”; Gammae, Helm, Johnson, Vlissides; Pearson 2016
Design patterns provide great means to communicate code, especially because they are by definition named. Many of these patterns are used on a daily basis. For example, most popular (imperative) programming language have adopted the “Iterator” pattern to make containers generically accessible through for-loops.
The original “Design Patterns” book (see citation above) has since its release been amended by many independent authors that have identified (named and abstracted) patterns in many different areas of code, not only object-oriented one. There is also language-specific patterns like the pimpl (pointer to implementation) pattern in C++.
If code resembles a design pattern or was written with a design pattern in mind it is often very easy to communicate what the code does. That is because the structure (the pattern) of the code can be understood independently of the application of it (e.g. what the actual use of the code is).
Math
Math often provides the underlying formulas and algorithms to solve a problem. If there already is a well-known (or at least well-documented) formula to solve a specific problem it is often a good idea to use it and name it in the code. For example if the euclidean distance is used as a distance measure it’s easy to communicate why the code is the way it is. It calculates a distance measure based on the known formula, which gives the length of a straight line between the points.
Analogies
Analogies are a great way to describe code. It takes the abstract, complicated and detailed code and provides a simplified explanation that “clicks” with cognitive patterns we already have. For example the “tree” analogy often used (which also is a math concept) helps to understand the structure of data and the algorithms operating on it.
Analogies are very versatile in communicating code, because we are able to find one for almost everything. Most good ones have already been formalized (i.e. stack, tree, queue, adapter, clone, map, inventory, spawning, forking, messages, topics…). But new ones may also be found (i.e. getting the newspaper as an analogy for a daily synchronization message).
Non-Verbal
Not all form of communication is verbal. When sitting in a meeting room together it is often a good idea to also make use of whiteboards, screens, paper and other communication aids. One of the most influential forms of communicating code (and systems) through diagrams is the Unified Modeling Language (UML). These diagrams are very popular among developers and also have great support in most documentation tools. Just drawing a semi-formal UML diagram in a meeting can really help participants visualizing the big picture of the code.
Very widely used algorithms might also have more complex visualizations like animated videos. For example, this is Wikipedia’s visualization of the bubble sort algorithm.
Von Swfung8 – Eigenes Werk, CC BY-SA 3.0, Link
With tools further advancing the prevalence of such animations and other communication aids will probably increase.
Conclusion
There are many ways to communicate code to fellow programmers. A few have been highlighted here. I would argue that being able to communicate code effectively and efficiently is one of the key (soft) skills for programmers collaborating in bigger projects. Be it through documentation or face-to-face. Even though good code is self-explanatory, most real world code isn’t and thus requires some kind of communication between collaborators.
Having a good set of techniques to do just that goes a long way and this post may only serve as an initial starting point for the topic.
