Skip to main content
replaced http://codereview.stackexchange.com/ with https://codereview.stackexchange.com/
Source Link

The code in the OP is extremely over-commented. (No offense)

The other answers have covered all the bases, very well, but there is one thing I want to emphasise from Yann Vernier's answerYann Vernier's answer:

The last comment demonstrates the biggest problem with comments that describe what the code does, rather than what it is intended to do. They invariably get out of sync, and at that point only cause confusion.

This is the biggest problem with over-commented code, in general. It's a serious concern:

  • Comments are just like anything else in a code-base, they have to be maintained.
  • Out of synch comments are not just worthless; they're dangerous.

Personally, I think under-commenting is preferable to over-commenting, any day of the week. An assignment is one thing; it doesn't change when you're done. But, most code lives on and a variety of people change it, each one having to digest and maintain both the code and the comments.

Please be selective when commenting.

The code in the OP is extremely over-commented. (No offense)

The other answers have covered all the bases, very well, but there is one thing I want to emphasise from Yann Vernier's answer:

The last comment demonstrates the biggest problem with comments that describe what the code does, rather than what it is intended to do. They invariably get out of sync, and at that point only cause confusion.

This is the biggest problem with over-commented code, in general. It's a serious concern:

  • Comments are just like anything else in a code-base, they have to be maintained.
  • Out of synch comments are not just worthless; they're dangerous.

Personally, I think under-commenting is preferable to over-commenting, any day of the week. An assignment is one thing; it doesn't change when you're done. But, most code lives on and a variety of people change it, each one having to digest and maintain both the code and the comments.

Please be selective when commenting.

The code in the OP is extremely over-commented. (No offense)

The other answers have covered all the bases, very well, but there is one thing I want to emphasise from Yann Vernier's answer:

The last comment demonstrates the biggest problem with comments that describe what the code does, rather than what it is intended to do. They invariably get out of sync, and at that point only cause confusion.

This is the biggest problem with over-commented code, in general. It's a serious concern:

  • Comments are just like anything else in a code-base, they have to be maintained.
  • Out of synch comments are not just worthless; they're dangerous.

Personally, I think under-commenting is preferable to over-commenting, any day of the week. An assignment is one thing; it doesn't change when you're done. But, most code lives on and a variety of people change it, each one having to digest and maintain both the code and the comments.

Please be selective when commenting.

Source Link
tiffon
  • 641
  • 4
  • 9

The code in the OP is extremely over-commented. (No offense)

The other answers have covered all the bases, very well, but there is one thing I want to emphasise from Yann Vernier's answer:

The last comment demonstrates the biggest problem with comments that describe what the code does, rather than what it is intended to do. They invariably get out of sync, and at that point only cause confusion.

This is the biggest problem with over-commented code, in general. It's a serious concern:

  • Comments are just like anything else in a code-base, they have to be maintained.
  • Out of synch comments are not just worthless; they're dangerous.

Personally, I think under-commenting is preferable to over-commenting, any day of the week. An assignment is one thing; it doesn't change when you're done. But, most code lives on and a variety of people change it, each one having to digest and maintain both the code and the comments.

Please be selective when commenting.