Monday, June 22, 2009

How to use comments wisely

How can comments be a security issue?

  1. If you have to use comments to explain your code, the code is probably too complicated. When creating a complicated solution to solve a problem you insert errors, bugs or just making it har to maintain.
  2. A comment that doesn´t describe the code correctly may lead readers of the code to think it does something it doesn´t, making it harder to maintain.
  3. Comments gets stale, when you change/refactor your code you´ll forget to change your comments. Se #2.
  4. It may be hard to correctly describe what the code does in plain text. Se #2.

Code should be written in a way to make comments redundant.
For example give methods, variables and fields names to describe what they do or what they are representing is a good start.

Use comments to document how to use classes and methods, for other programmers using them to know how to. Be sure to update the documentation as you change/refactor the code.

Finally a quote I really like:
"When I have a specific goal in mind and a complicated piece of code to write, I spend my time making it happen rather than telling myself stories about it." - Steve Yegge

No comments:

Post a Comment