Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
10  
If you are using a document generation system like JavaDocs or Doxygen, comments are literally documentation. –  Steven Burnap May 14 '12 at 2:13
4  
YANGNI (xprogramming.com/Practices/PracNotNeed.html). Document your code to your satisfaction. Let the customer (if there is ever one) pay you to write the documentation to their satisfaction. Don't worry about what a lot of people you talk to say (unless they are paying you). –  emory May 14 '12 at 4:59
1  
Of your 2 comments the 2nd is useless, why not replace $foo with bar. If this is not true then the comment is wrong. The first comment is wrong. It is an assignment. –  richard May 14 '12 at 13:06
2  
When ever you wish to add a comment, change your code to be so clear that it needs no comment. Everything is documentation, code is documentation, Comments usualy have no [additional] information, or are wrong. Document the intention the what (code contracts can help with this), and the why. Keep documentation close to the code, use comments. Documentation over Documents: Comments over Documents, Clear Code over Comments. –  richard May 14 '12 at 13:11
2  
Is YANGNI "you ain't not going to need it" –  Chris S May 14 '12 at 15:03

6 Answers 6

up vote 26 down vote accepted

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.

share|improve this answer
3  
"For most projects, comments are the primary (if not only) form of project documentation." - tempting to downvote for this but unfortunately it must be admitted as a true statement. I hope though that it is not your intention to claim that this is how things should be. –  Crazy Eddie May 14 '12 at 6:59
2  
I really disagree with this, as the only reliable documentation you have is the source code itself. Both comments and "documentation" have to be maintained with the code, which seldom happens. So the only reliable source of documentation is your code! –  martiert May 14 '12 at 7:18
3  
@martiert I used to feel the same way, but I found this doesn't really work as well in practice. All of those "why" comments are much clearer as comments than trying to extract "why" knowledge from code. Certainly self-documentation code can (and should) be used to remove most comments, but sometimes a comment is the simplest, clearest, and most time efficient way to document something. –  Oleksi May 14 '12 at 13:50
3  
@martiert The problem with self-documenting code is that it doesn't permit references to documentation elsewhere. Some of the best comments in code that I've ever seen have been references to academic papers that explained the details of the algorithm used or the selection of magic constants. No amount of self-documenting is going to help avoid the fact that some, critical, documentation is just plain non-obvious. The “why” often falls in this category, and sometimes the “how” does too. –  Donal Fellows May 14 '12 at 14:48
3  
Also note that comments, in many languages, are used to generate the actual documentation... so they're are often one and the same. See the MSDN as an example. –  Steve Evers May 14 '12 at 16:40

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.

share|improve this answer
15  
Self documenting code is a lie. –  Yannis Rizos May 14 '12 at 4:25
1  
@YannisRizos More like an unattainable goal than an outright lie. –  Ptharien's Flame May 14 '12 at 4:47
2  
@YannisRizos: you may be right, but code which needs lots of comments is almost ever very bad code and could be almost ever written in a manner that it needs less comments. –  Doc Brown May 14 '12 at 6:32
8  
@DocBrown Depends. I've seen people documenting for loops and I've seen people claiming that a 100 loc of business logic was self documenting. Fact is that excessive comments can't hurt (except if obsolete/incorrect), and if I have to choose between excessive commenting and self documenting code, I'll always choose the first. Of course, I'd pretty much prefer balanced and to the point comments, like Oleksi describes. –  Yannis Rizos May 14 '12 at 7:09
1  
@MathAttack Most decent IDEs can hide / fold comments. But yes, sometimes they just get in the way. –  Yannis Rizos May 14 '12 at 10:43

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
1  
Truly tricky stuff should be in an academic paper (or, occasionally, patent). –  Donal Fellows May 14 '12 at 14:51

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.