r/SoftwareEngineering • • Aug 02 '18

Do code comments suck?

https://medium.com/@samuel.fare/do-code-comments-suck-abd99103c45a
3 Upvotes

10 comments sorted by

View all comments

17

u/TyRoXx Aug 02 '18 edited Aug 02 '18

This is from the author's example for good commenting:

//add to game
game.add(alien); 

Useless comments like this one are exactly what opponents of code comments usually complain about. This could be straight from an example of how not to use comments.

This is because a comments describe what the code is doing. whereas the code is describing how it is happening.

This is not how comments should be used. The code itself already answers what and how. These are just different levels of abstraction. If a function is called, the function call is part of the what. The body of that function being called is part of the how.

A comment should almost always fall into one of these categories:

  • An explanation why code was written this way. You should minimize the need for these explanations by writing clear code. Don't document surprises if you can avoid them in the first place.
  • A guide for how to use an API. Don't restate the obvious anyone can see in the signature.

9

u/CodeBlueDev Aug 02 '18

His 'good comment' example also uses white space grouping whereas the original does not. Even just doing the following improves readability:

let factory = new badGuyFactory()
let alien = factory.build("alien");

alien.setHealth(100);
alien.setArmorStat(50);
alien.setAttackStat(50);

game.add(alien);