CODEWITHSUNDEEP
ruby-on-rails
Starkers
Starkers

Reputation: 10551

Code commenter gem

I was sure a few months ago there was a gem that made sure you've commented every single line of code. Or at least every single action. If you hadn't, it brought your attention to it after you'd run some sort of rake task.

Can't remember for the life of me what it was called.

But is it a good idea to comment every single line of code? I say yes, it solidifies your knowledge, gives you a last change to catch bugs/security holes and eases future development.

However, projects in github and really sparsely commented. Personally, I need to comment most lines before I start to realise what a piece of code does. Is this not the case for most? Do comments just trip the code ninjas up?

Upvotes: 0

Views: 41

Answers (2)

Dave Newton
Dave Newton

Reputation: 160321

Commenting every single line of code is a horrible idea:

  1. It's noisy and obfuscates the source
  2. It becomes out of date trivially easily

Things to comment:

  1. Tricky and/or hacky code
  2. Complicated algorithms
  3. Why something is doing what it's doing

Those comments should almost always live at the method level.

  1. If a code block needs a comment it should probably be a method
  2. If a line of code needs a comment it should probably be refactored

Code should speak for itself as much as possible. Appropriate naming goes a long way to eliminating the need for wads of commenting. Some documentation may absolutely be necessary, but in the case of large structural comments, it may make more sense to keep it out of the code, and in your wiki.

Upvotes: 1

Cereal
Cereal

Reputation: 3849

No, it's not a good idea to comment every line of code. A lot of code is self-explanatory. In fact, you should strive to make your code self-explanatory.

For example, you would never want to comment the following:

sum = 1 + 3

You should save your comments for things that need explaining.

What I think you mean is a gem that enforces proper documentation. Documentation is a comment that explains the purpose of a method or class, as well as details its parameters and return values.

Regarding the gem you're thinking of, it may be rubocop.

Upvotes: 0

Related Questions