DEV Community

We Don't Need No Steenking Comments

Thomas H Jones II on September 27, 2019

Do you document or comment your code. Other day, as I was finishing up writing an automated system-restore tool for one of my customers, I looked a...
Collapse
 
curtisfenner profile image
Curtis Fenner • Edited

Certain kinds of comments are very useful.

Many comments that get written range from useless to harmful (because they actually lie/mislead). However, I think there's many more comments that aren't written but should be.

The code says what the computer does. If you are a programmer, then you can read the code. Unless you're doing something absurdly tricky, you don't need comments to explain what the code is doing; if you feel like you need comments to explain the programming language, you are usually doing something wrong. This is the category of comments which are useless or harmful; there are often too many of these.

Code cannot speak for itself in why it is written one way.

Sometimes these are still technical details, like performance, allocation, and security; these are generally not encodable in the programming language itself. These aspects of the code deserve comments, since there are pertinent technical details that cannot be a part of the code itself.

There are also outside / product concerns which the code may execute but it's unclear what the actual requirement is (why does this job execute every Monday? Is there something special about Mondays, or does it just need to be done 'often enough'? How often is 'enough'?)

These are the comments that are very useful. I don't see enough of them.

Collapse
 
ferricoxide profile image
Thomas H Jones II

For me, it's usually a "breadcrumbs" exercise. I have to switch projects and languages with a non-trivial degree of frequency. If someone asks me to re-visit something, having the comments helps job my memory for why I did something a given way (especially if it's been many months and I've changed the way I tend to do a given thing).

Collapse
 
ehorodyski profile image
Eric Horodyski • Edited

These days, I only will use comments that get picked up by IDEs or are used for generated documentation purposes.

For instance, I'll write an Angular library and use Compodoc to make sure I have enough comment coverage and put examples in the JSDocs for my team to use. If I'm implementing an authorization library, my team needs to see examples on how to use it e2e.

Also, I want my code readable by IDEs so that my team can use my code and know what functions do. It's almost as important as the IDE picking up my library's method signatures.

I usually don't write any inline comments these days. I spend my time making sure that variable names are explanatory and the code is readable, by breaking up chunks of code around white lines (like first 3 lines are variable declarations, then a new line, then an if block, then a new line, then return statement). I'll even do things like create extra variables that can easily be embedded somewhere in order to increase readability (like creating a headers variable when I can inline it into an HTTP call). We don't need maximum performance these days thankfully, so making sure my code is readable is paramount.

Collapse
 
ferricoxide profile image
Thomas H Jones II

Yeah, when I got the "71.2% was actual code" figure, the non-code was inclusive of "readability null-lines" ...which is likely at least 1/3 of the non-code percentage.

Self-explanatory variable names is open to debate. Something that's obvious to you or me isn't obvious to a casual observer. Plus, having really old habits, I'm not a fan of variable-names that eat up half the 80-column page-width I prefer to keep within (yeah: I generally don't write Java code or languages with similar 'run-on' naming-conventiosn).

Collapse
 
philipstarkey profile image
Phil Starkey

I would say anything up to 50% would be acceptable. Obviously 50% would be uncommon, but I would think there are a few circumstances where it is appropriate.

I think it also depends on your coding style. I often sketch out what I want to achieve in comments first, and then fill in the blanks. This then leaves a record of what was intended, which can be very helpful when revisiting something once a bug is discovered as it quickly triages the bug into either "the code doesn't do what it should" or "we didn't think of this case when writing the code". But it does mean you can end up with some long comments. Doubt I've ever hit 50% though, but I've probably hit 30%.

I would be interested to know what percentage were comments vs blank lines though, as I was surprised you lumped them together in your count. They seem like quite distinct groups of "lines of code that can be removed".

Collapse
 
ferricoxide profile image
Thomas H Jones II

For me it's mostly "I'm likely to need to cold-revisit this 6-18 months later: leave myself a trail of breadcrumbs to search for".

Even the nearly 29% "not code" of the particular tool isn't purely commentary: at least a third of that was "readability" null-lines. I lumped them together because I was more interested in "how much of this is actual code" vice "how much of this is 'helper' content" (searchable-comments or 'readability' blank-lines).

Collapse
 
elmuerte profile image
Michiel Hendriks

I do documentation comments on public APIs, unless they are setters/getters.
Other than that I only add comments when I feel I should explain why, as I might not recall it in the future.