Abstraction in Elm: Introduce Comments

Table of Contents

1. Introduction
2. One Expression to Rule Them All
3. Introduce Comments
4. Introduce Local Functions
5. Utility-Based Modularization
6. Domain-Based Modularization
7. Wrappers and Generics for Everything
8. Conclusion

Code

Discussion

It has been suggested that commenting is an appropriate mechanism for making code relationships clear. In some senses, commenting does the job. It can no longer be said that this code is completely ambiguous. The author’s intent is now clear, and the relationship between the run status and the animation is apparent as well.

However, I tend to call this level of abstraction (if that is an even appropriate term) “superficial abstraction.” There are two reasons for this. Comments do not address duplication, and they are highly prone to becoming stale.

Let’s suppose that, in the above code, I want to make a change to the duration of the color oscillation effect. With the current structure (which, to be clear, is the same as the previous example — utterly concrete), I must go searching for all instances of setting duration in a color oscillation and update them all individually. The rampant duplication is still a major problem. I can understand the code’s intent, but making changes remains cumbersome and error-prone.

The problems become more severe if I have a large team. Because comments have no impact on the compiler or the execution of the compiled software, it is possible to change the software’s behavior to do something other than what the comments say it does. When comments are the abstraction pattern of choice, engineers who change the code must remember to change both the source code and the associated comments. As the system grows more complex, comments may come to describe parts of the code that are not in their immediate vicinity (such as line 46 above). An engineer is unlikely to go searching through the code to find all the comments they have affected with a change to the code’s behavior, and the compiler will not be able to stop them. Comments such as these inevitably become lies, and when that happens, ambiguity will return in full force.

Analysis

Pros

• There is zero ambiguity in terms of what is being executed.
• Comments provide a simple way to clarify why the code is doing what it’s doing.
• Relationships between various portions of the code are now clear.

Cons

• The clarity of the why and the relationships are contingent upon engineers maintaining the cohesion of the code’s behavior and all associated comments with every change they make. As a system grows larger, comments will start to refer to parts of the code further and further from their own location, and dissolution becomes inevitable. At this point, the relationships and the why will become as muddled as having no abstraction at all.

Continue to Abstraction in Elm: Introduce Local Functions.