11

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?

Dynamic
  • 5,746
  • 9
  • 45
  • 73
  • 11
    If you are using a document generation system like JavaDocs or Doxygen, comments are literally documentation. – Gort the Robot May 14 '12 at 02:13
  • 5
    YANGNI (http://www.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 04: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. – ctrl-alt-delor 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. – ctrl-alt-delor May 14 '12 at 13:11
  • You are the first customer, but don't over complicate it. – ctrl-alt-delor May 14 '12 at 13:11
  • http://en.wikipedia.org/wiki/Literate_programming – SK-logic May 14 '12 at 14:13
  • 2
    Is YANGNI "you ain't not going to need it" – Chris S May 14 '12 at 15:03
  • @richard I was making it clear that whatever is after the # is a comment. – Dynamic May 15 '12 at 18:49
  • OK I will answer your question, Wouldn't this be considered documentation? Unfortunately yes by many. I have been a developer that has been asked to maintain code that has many comments, that are wrong or useless. They make the code hard to read. You have to ask: does it make it easier to read (maintain/review), how else can I make it easier to read. – ctrl-alt-delor May 16 '12 at 08:37
  • see also: [“Comments are a code smell”](http://softwareengineering.stackexchange.com/q/1/31260) – gnat Nov 08 '16 at 07:21

6 Answers6

27

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.

Oleksi
  • 11,874
  • 2
  • 53
  • 54
  • 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. – Edward Strange May 14 '12 at 06: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 07:18
  • @martiert I disagree. Reality must be a mix of both: actual code shows "what" is done, but not "why". Plain code also doesn't point to external documentation (such as an article describing the clever algorithm you used). This answer does advocate getting rid of redundant comments, so what is the problem? – Andres F. May 14 '12 at 13:09
  • @CrazyEddie I didn't mean to imply that lack of external documentation was good. I've updated the answer to be a little more clear about that. :) – Oleksi May 14 '12 at 13:47
  • 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. – Steven Evers May 14 '12 at 16:40
  • 1
    @DonalFellows: not just that but in commercial code, references to bugs or requirements are essential. You often do not know why a piece of code was changed unless you have these links, and they can only be entered as a comment. – gbjbaanb May 14 '12 at 18:43
  • I agree with your arguments, that the "why" is perhaps not as well explained in code, and self documenting code is not enough for customers. Problem I tried to make is that comments are most likely not 100% up to date with the code, as changes in the code sometimes will require a change in the comment. If this doesn't always happen, the comment will no longer document the code exactly. Therefor the code is the only reliable documentation, no mater if the code is self documenting or not. If you need comments, write them at the top of the function instead of inside functions. – martiert May 15 '12 at 06:51
12

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.

MathAttack
  • 2,766
  • 18
  • 22
  • 17
    Self documenting code is a lie. – yannis May 14 '12 at 04:25
  • 1
    @YannisRizos More like an unattainable goal than an outright lie. – Ptharien's Flame May 14 '12 at 04: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 06:32
  • 9
    @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](http://programmers.stackexchange.com/a/148473/25936). – yannis May 14 '12 at 07:09
  • @YannisRizos - You are correct. The one caveat is sometimes tooany comments can interfere with readability but that is the exception. – MathAttack May 14 '12 at 10:31
  • 1
    @MathAttack Most decent IDEs can hide / fold comments. But yes, sometimes they just get in the way. – yannis May 14 '12 at 10:43
  • I always at least write a single sentence describing in natural english what the function does. I also write class descriptions in a single sentence. `// Represents a practitioner at a clinic.` or `// Gets the available times of a practitioner at a clinic on a specific date.`. Code should always try to be as obvious as possible, but frankly, basic documentation is not only good to have, it also separates code segments when highlighted in syntax. – Nick Bedford Oct 19 '18 at 05:36
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.

John Bode
  • 10,826
  • 1
  • 31
  • 43
3

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.

Community
  • 1
Chris S
  • 899
  • 6
  • 11
2

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.

2

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.

Mike Hogan
  • 131
  • 5