4 ms·
Which leads me to another pet peeve: javadoc comments. Too many times I work on legacy code that where one third or less of the contents have comments -- HU
by Roboprog 14y ago
Which leads me to another pet peeve: javadoc comments.
Too many times I work on legacy code that where one third or less of the contents have comments -- HUGE, flowery blocks, and the rest have NOTHING.
I'd much rather have a short sentence starting with a verb, and not "this method will endeavor to attempt to proceed to ..." :-)
- pjscott 14y agoYes. Verbs! Good things. (No explicit verbs in this paragraph, though.) In any case, the comment for a class or method (or whatever) should start with a quick, concrete one-sentence description of what it is or does -- preferably starting with a verb, as you said. If you want to elaborate later, great, but everything needs the one-sentence summary. If I could tell inexperienced programmers one thing, this would be a strong contender. (Other possibilities include "Write your programs in discrete pieces that you can test in isolation, as much as possible," and "Make it work before you make it fancy.")