re: We Don't Need No Steenking Comments VIEW POST


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).

code of conduct - report abuse