3 ms·

I did this early in my career then stopped when I realized it generally made the code less readable. Generally, not always. Sometimes a comment about what the c

I did this early in my career then stopped when I realized it generally made the code less readable. Generally, not always. Sometimes a comment about what the code does is invaluable if it’s complex, but usually it is redundant with reading the code directly. I feel like coming across code littered with comments about what the next line does reflects someone not cleaning up after themselves, a string of trivial comments would not pass code review on most teams I’ve been part of.

314 4y ago
This applies to comments about single statements in the code, unless they have an esoteric side-effect or there is a particular why that needs to be explained. But comments that describe a paragraph/block of code have a separate value. Being able to skim code faster because of a series of well chosen sentences is an aide beyond clear code. As the OP described it is a good way to design before the code is written.