Are comments considered a form of documentation?

Question

When I am writing small scripts for myself, I stack my code high with comments (sometimes I comment more than I code). A lot of people I talk to say that I should be documenting these scripts, even though they are personal, so that if I ever do sell them, I would be ready. But aren't comments a form of documentation?

Wouldn't this:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

be considered documentation, especially if a developer is using my code? Or is documentation considered to be outside of the code itself?

Answer 1

Comments are definitely documentation. For most projects, comments are (unfortunately) the primary (if not only) form of project documentation. For this reason, it's very important to get it right. You need to make sure that this documentation stays accurate despite code changes. This is a common problem with comments. Developers often "tune" them out when they're working in familiar code, so they forget to update comments to reflect code. This can create out-of-date, and misleading comments.

A lot of people suggest making the code self-documenting. This means that instead of comments, you restructure your code to remove the need for them. This can get rid of most of the "what" and "how" comments, but doesn't really help with the "why" comments. While this might work effectively to get rid of most comments, there are still plenty of times where writing a comment is the simplest and most efficient way to document a piece of code.

Answer 2

They are a form of documentation, but remember that documentation is in the eye of the beholder....

• For some, self documenting code is enough. But that assumes a level of technical detail as the customer. We should be careful thinking that this is enough, because our ego may tell us "It is obvious what this code is doing" but time can prove otherwise. It also assumes you know in advance the skills of the reader.

• For those looking at source code but with less technical expertise, comments could be ok. But that assumes someone is looking at the source code.

• If you're technical, but lacking the time to read all the source code, a technical manual could be what's required.

• An if the user lacks technical skills, but just needs to know what is happening, user documentation is what's needed.

So the real question is who is your customer? If you are, then self documenting code or comments is enough. If it's for someone else, you might want to broaden how you document.

Answer 3

Yes, comments are a form of documentation. Whether or not they're useful documentation for someone who has to maintain or update your code is an open question.

I know you meant it as a throwaway example, but stuff like

print $foo; # this prints "bar"

isn't useful; it just adds visual clutter. Don't document the obvious.

Block comments at the head of a method or function definition that describe the function or method's purpose (in high-level terms), inputs, outputs, return value (if any), exceptions (if any), preconditions, and postconditions are useful, but only to the degree that they tell someone how the function or method is supposed to be used. They don't explain why the function exists.

If someone else needs to maintain your code, then you need to document the requirements and the design somewhere, and that's typically not done in the source code itself.

Answer 4

I find sticking to Bob Martin's approach to this, from Clean Code, usually solves the problem of whether you think you're over commenting or under commenting and leaving out documentation:

We are authors. And one thing about authors is that they have readers. Indeed, authors are responsible for communicating well with their readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.

...the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.

So in other words, is your code is self explanatory without the documentation? There's no set rule for it (unless you work for somebody like Microsoft whose documentation is publicly accessible), it's mostly down to helping the future reader of the code which is often you.

Answer 5

Documentation should document the Why not the How. The How should be self-evident in the code, that is unless it is some arcane optimization trick or other language specific technique that is not commonly occuring.

The Why probably should not be in code, it should be somewhere else like a product backlog, that is tied to commit comments with story ids that can be searched for in a change log or branch name.

Answer 6

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.