Code is about How, Comments about Why

Look at some of my other responses to this. Your criticism is covered in other replies. In short I would say code does not really convey intent. It explain how something is done. You write code to instruct the computer how to do a task. We use high level languages to make that description of how the taks should be done readable to humans.

However to convey why it needs to be done in the first place, you need some comments. Code can tell you how data is sorted, but you need a comment to tell the reader why it needed to be sorted in the first place.

As for the comments getting out of sync. That problem is no different for code. Name of functions and variables often get out of sync. Languages don’t enforce that the meaning of a variable corresponds to its name.

In many regards wrongly named variables and functions is a significantly worse problem, and can often be much harder to deal with. Maintaining an interface may make it impossible to change a function name. Comments in contrasts are much easier to update.

And lets not forget that you don’t need to like comments to provide them or keep them. The only thing that matters is that you accept that other developers are not the same as yourself. Some developers benefit from comments, and there is no absolutely no reason they should not be accomodated. If you don’t like or trust comments, you can simply ignore them. Nobody is obliged to read a comment, if they don’t like them.

All too often the subsitute for a comment becomes that the information which could have been stored in a comment gets stored in the head of a developers which must frequently be consulted each time another developer wants to change a piece of code that developer knows how works.

Keeping essential information stored inside the head of a developer, is a fragile system. He or she is prone to forget that information or that person may simply leave the company at which point the information is lost forever. A comment in contrast is durable.

Written by

Geek dad, living in Oslo, Norway with passion for UX, Julia programming, science, teaching, reading and writing.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store