Skip to main content
Software Engineering

Return to Answer

Improved formatting.
Source Link
edit approved May 20 at 13:47
RokeJulianLockhart
edit approved May 20 at 13:47
RokeJulianLockhart
  • 103
  • 4

Comments are a form of documentation. AnAn inferior form, and one that suggests you have located an area of your code that can be better factored.

It sounds like you comment things compulsively. HavingHaving other options may be a good thing. II can think of three superior forms of documentation:

  1. Factor your code better. InsteadInstead of adding in a comment, extract a method or function whose name is the text of the comment you were about to write. SoSo the code says what your comment was about to say.

  2. Tests. ThisThis is the form of documentation I usually search out. Unit tests and acceptance tests are living documentation, and can read easily if lots of meaningful methods are used to express intent, as in point 1.

  3. For scripts, the --help--help option. This is where you can go nuts on doc. Stick in examples, anticipate what the user would need.

In summary, if you find yourself inclined to stick in a comment, check if there is a way to communicate to the reader by structuring the code better. OrOr is there a test that communicates why that code is there? If you still feel inclined to comment it, admit defeat, and do it.

Comments are a form of documentation. An inferior form, and one that suggests you have located an area of your code that can be better factored.

It sounds like you comment things compulsively. Having other options may be a good thing. I can think of three superior forms of documentation:

  1. Factor your code better. Instead of adding in a comment, extract a method or function whose name is the text of the comment you were about to write. So the code says what your comment was about to say.

  2. Tests. This is the form of documentation I usually search out. Unit tests and acceptance tests are living documentation, and can read easily if lots of meaningful methods are used to express intent, as in point 1.

  3. For scripts, the --help option. This is where you can go nuts on doc. Stick in examples, anticipate what the user would need.

In summary, if you find yourself inclined to stick in a comment, check if there is a way to communicate to the reader by structuring the code better. Or is there a test that communicates why that code is there? If you still feel inclined to comment it, admit defeat, and do it.

Comments are a form of documentation. An inferior form, and one that suggests you have located an area of your code that can be better factored.

It sounds like you comment things compulsively. Having other options may be a good thing. I can think of three superior forms of documentation:

  1. Factor your code better. Instead of adding in a comment, extract a method or function whose name is the text of the comment you were about to write. So the code says what your comment was about to say.

  2. Tests. This is the form of documentation I usually search out. Unit tests and acceptance tests are living documentation, and can read easily if lots of meaningful methods are used to express intent, as in point 1.

  3. For scripts, the --help option. This is where you can go nuts on doc. Stick in examples, anticipate what the user would need.

In summary, if you find yourself inclined to stick in a comment, check if there is a way to communicate to the reader by structuring the code better. Or is there a test that communicates why that code is there? If you still feel inclined to comment it, admit defeat, and do it.

Source Link
Mike Hogan
Mike Hogan
  • 131
  • 5

Comments are a form of documentation. An inferior form, and one that suggests you have located an area of your code that can be better factored.

It sounds like you comment things compulsively. Having other options may be a good thing. I can think of three superior forms of documentation:

  1. Factor your code better. Instead of adding in a comment, extract a method or function whose name is the text of the comment you were about to write. So the code says what your comment was about to say.

  2. Tests. This is the form of documentation I usually search out. Unit tests and acceptance tests are living documentation, and can read easily if lots of meaningful methods are used to express intent, as in point 1.

  3. For scripts, the --help option. This is where you can go nuts on doc. Stick in examples, anticipate what the user would need.

In summary, if you find yourself inclined to stick in a comment, check if there is a way to communicate to the reader by structuring the code better. Or is there a test that communicates why that code is there? If you still feel inclined to comment it, admit defeat, and do it.