Useful and useless code comments
I’m on the same page. Just look at the given example. Does it look wasteful to say that you’re adding a vertical bar when you have the following line of code?:<p><pre><code>  &#x2F;&#x2F; Add a vertical scroll bar
  vScrollBar = new JScrollBar(JScrollBar.VERTICAL);
  add(vScrollBar, BorderLayout.EAST);
</code></pre>
Perhaps. But the comment is making a lot more than simply describing what’s below of it. The comment is doing the following things:<p>- It’s creating a visual boundary that aids to the readability of the code. It adds context within a large set of instructions.<p>- It’s providing context that might not be there for the person who is reading the code. Just because you think the name of that function and what you’re passing into it clearly describes the instruction, doesn’t mean that everyone else does. At least not in a snap. The comment helps to reduce the cognitive load of reading the code because it’s explaining the instruction in plain english.<p>- The comment itself could be part of a larger narrative that is trying to explain what that file is doing. It’s not there to make the obvious more obvious. It’s there to  make the whole file obvious which is evidently important to write readable code.<p>Look. I know there are purists that get offended with obvious code comments. But you cannot expect everyone to have the same proficiency you do. Writing good code, also means writing code that a newbie can at least comprehend. And sometimes that means explaining in plain english what could be already obvious to you.<p>People like to think they are writing code like prose that is delightful to the reader, but many times are just writing reader hostile code.<p>Write code focusing on clarity.  Not elegance by obscurity. Make it clear, add structure, add visual boundaries. Ask yourself if what you think is obvious is obvious to everyone. If in doubt explain it with a comment. I’ll rather see an obvious comment and say “well that’s obvious” than spending valuable time trying to understand what certain piece of code is doing.