While running on the beach I stumbled upon the bottle below. Inside was a memorando to the writers future self detailing present events and pitfalls.
In a way, that’s what commenting should be about; a message to thy future self about the why’s of here and now. You’re most likely not the one who’s going to read it, but that rusty piece of code, washed away by years of sunshine and salt you left for the world, will be much better with a message attached.
The message I found was emotionally sound and really everything you’d expect from a silo to the future. Writing proper comments though, even considering the poetic aspect of coding, should stick to some rules always handy to remember.
1) Remember that code is always better than comments.
While the following Java method comment may look ok, it probably has better alternatives.
If you’re using an editor like IntelliJ you can use @Nullable or @NotNull to make your intentions specific. If not you always have the handy Option<String> which will add run-time checking.
2 Document intention, not functionality
From the programmers' bible Code Complete you get that IBM did a several months study where maintenance programmers reported that the most difficult problem they faced was getting the authors original intent.
The above regex parses emails. The comment above merely describes a problem the programmer had with Top Level Domains. It’s not descriptive of its intent but merely focuses on the functionality. The following comment not only specifies the intent but also provides the foundation for the chosen rules.
While hard to do while your mind is focusing on the problems at hand, comments will provide the higher level of abstraction needed for your latter self.
About that bottle? I did what anyone would do, tagged it with #mafaldasmessageinabottle and freed it back to the ocean.
Originally published at wasteofserver.com on July 1, 2018.
