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 at my editor's line-count and noticed a higher-than-expected number. I quickly ran the file through a filter to squash out all the blank and comment-lines and found that the resultant file was 71.2% the line-count size of the commented/formatted file. Just wondering if that's "normal", high or low.
For further actions, you may consider blocking this person and/or reporting abuse
Top comments (7)
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.
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).
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.
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).
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".
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).
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.