While running on the beach I stumbled upon the bottle bellow. 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.

Stumbled upon this last afternoon

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.

// returns null if no such user is present (PROBABLY BAD COMMENT!) 
public void String getUserNameById(long id);

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 long study where maintenance programmers reported that the most difficult problem they had faced was grasping the authors original intent.

// allows the usage of 6 digit TLD's (BAD COMMENT)
\b[A-Z0-9._%+-][email protected](?:[A-Z0-9-]+\.)+[A-Z]{2,6}\b

The above regex parses emails. The comment above merely describes a problem the programmer had with Top Level Domains. It’s not descriptive of it’s intent but merely focuses on the functionality. The following comment not only specifies the intent but also provides the foundation for the chosen rules.

// parses emails according to RFC3696 - https://tools.ietf.org/html/rfc3696#page-5
\b[A-Z0-9._%+-][email protected](?:[A-Z0-9-]+\.)+[A-Z]{2,6}\b

While hard to do while your mind is focusing on the problem at hand, comments must focus on the why's and not the how's. Only very arcane how's should be documented if needed to provide insight into the why's.

About that bottle? I did what anyone would do, tagged it with #mafaldasmessageinabottle and freed it back to the ocean.