Too much documentation?

[melguin]

I don't think that many here will argue against documenting your code well. It's something that I have tried to do from that beginning, and have finally gotten into the habit. I try to say what's going on where, what each subroutine does/takes/returns, etc.

However, I was recently looking at my code, while working on some other projects written by others and noticed that although they used some comments (less than I would call a minimum) mine have about ten times the amount in some places. Then I started really looking at my code and noticed that, in general, my code to comments ratio ranges from 5:1 to 2:1.

Does anyone see anything wrong with this, or should I keep on doing what I'm doing? Does having a large amount of comments slow the code down, or are there other disadvantages? How do you find a balance?

melguin.

[Corion]

In a talk on YAPC::Europe, Michael Schwern claimed that the breakdown was something like 40% code, 40% documentation and 20% comments in the code, but note that he's heavy on writing (code-)user documentation together with the code.

Personally, I tend to use very few comments, as I feel that my code should speak for itself - and any piece of code that I think could do with more comments is a good target for rewriting. Most of my comments only state what's happening (supposed to happen) as the programs goal, and not how it is achieved, except maybe for the design pattern used to implement the behaviour. But one reason why this works is, that I try to "speak" in the language I program in, that is, I try to only use idioms of that language to accomplish what I need. If I were to implement less known algorithms or heuristics, they would need plenty of documentation.

[Sherlock]

Always remember that the purpose of documentation is to make it clear to anyone (including youself, 2 months down the road) what the code is doing, or supposed to do, at least. Therefore, I think that the amount of commenting that you do will be dynamic. If you're doing some rather complex things, perhaps dealing with nested data structues, etc., you might need more comments (your 2:1 ratio). However, if you're doing something fairly simple and straight-forward, you'll obviously need less comments (your 5:1 ratio). How many comments you put in is really your judgement.

I feel that how complex something is not only relates to how complex the operations or data structures are, but also how complex the syntax is. IMO, I think one thing that endears Perl to so many here is that it is a very expressive language. That's great for the developer (less typing) but it's much harder to read. Therefore, I'd hope to find (in general) more comments in a Perl program than in a Java program. (Please note that I said "in general," so take that with a grain of salt.)

I've seen this go both ways. In one extreme case, I saw documentation plans that were so thorough that the developers wrote about 30 lines of documentation to 5 lines of code...for those scoring at home, that's a 1:6 ratio. Obviously, that's not good, as the documentation becomes more of a burden than a benefit. I've also seen code that has no comments in it. You already know that having no comments isn't good, or you wouldn't be posting, so I say no more.

To put it bluntly, I don't think anyone can tell you how much documentation is the right amount. That's really up to you. I like hearing someone say, "You should have 20% documentation blah blah blah" because it gives me something to shoot for, but that should only be a guideline. The real decision of how much documentation to have is up to you. Determine what you need to say to make the code make sense and say it, and no more.

I wish I could be of more help. Good luck.

- Sherlock

Skepticism is the source of knowledge as much as knowledge is the source of skepticism.

[Cirollo]

Comments will never slow your code down. When your script is run, comments are simply thrown out, since they have no impact on the actual workings of the program.

The only disadvantage to having a huge amount of comments is that you may be causing confusion. Try to be concise and clear, but use as many words as you must to get your point across.

Bad comments are ones that are completely obvious simply from looking at the code. For example,

# Print the contents of the string variable $foo
print $foo;

That comment would be worthless, since even a non-programmer can just glance at the code and tell what it does.

[clintp]

This is the one of the many Holy Wars that programmers engage in. Beware of the power of the dark side.

For me, I put the complexities in my data, document the data and call it a day. Sometimes it's necessary to provide a road map for large programs, but any more than a couple of lines of comments for each function means that I'm doing something wrong.

The one exception to this being places in the code that I know are going to have to be changed: a future programmer will have to meddle in it, and a config file would be overkill. These I block out to be obvious, and then document each and every single thing carefully.

[Beatnik]

I hardly ever comment my code and the documentation I DO write sucks bigtime... There, I said it... happy now?? :))

Like mentioned before commenting code should be a reflex, and someday I will train it. Right now I'm lazy (and Larry said Laziness is a virtue). I doubt you can have TOO much documentation, like you can't have TOO much sex (hear that, hun??) or TOO much O'Reilly (Manning too) Perl books.

I get comments constantly for not providing documentation and POD for my code/apps; my excuse usually is something like 'But it's still beta... I'd be a fool writing documentation for code that's probably gone change anyway...'.

If New Year were today, my New Year's resolution would definitly include writing more documentation and POD, together with finally security checking code, bribing vroom with beer again and slowing down my XP gaining so OeufMayo can catch up.

Greetz
Beatnik
... Quidquid perl dictum sit, altum viditur.

[crazyinsomniac]

The balance is achieved when self documenting code passionately blends with your comments, creating a mesmerizing story an infant programmer can understand without feeling lost for more than a second.

 
___crazyinsomniac_______________________________________
Disclaimer: Don't blame. It came from inside the void
perl -e "$q=$_;map({chr unpack qq;H*;,$_}split(q;;,q*H*));print;$q/$q;"

[quidity]

40 percent is about right, but there is quite a large spread, see Some simple metrics.

[chumley]

This is something that has changed for me several times over the years. When I first started, with BASIC, I used "A", "B", "C", etc. for variable names and didn't document anything. Fortunately I had nun for a CS teacher who beat that habit out of me. (Sorry... pun unintentional!)

Lately I have tried to use descriptive names for variables and routines, short comments where they're needed, and larger blocks of "pretty" comments to break up major sections. For example I am working on a project at home that uses both DBI and Tk. I am putting Tk-related functions in one section, and DBI functions in another, separated with something like this:

############################################################
#
# This is the "meat" of the program where all the
# database stuff is hidden. Everything up to here
# is the Tk interface.
#
############################################################

I also try to choose subroutine names and variable names so they make sense. For example:

sub get_subject_list
{
    my @list;
    my $topic;

    my $dbh = DBI->connect("DBI:CSV:");
    my $sth = $dbh->prepare("SELECT subject FROM subjects");
    $sth->execute();

    while( $topic = $sth->fetchrow_array )
    {
        push(@list,$topic);
    }    

    return @list;

    $dbh->disconnect();

}

It should be fairly obvious what's going on here. At least, if I read this code in a few months I will know what's going on.

So far this program prints out to 5 pages, with about 55 lines of comments. That's close to the 5:1 code to comments ratio that melguin mentions. I may add a long section at the top which documents all the naming convections and subroutines I used, but that comes later. I also find it easier to put the POD at the end of the file after all the Perl code. I have tried interspersing POD in the code but it didn't work well for me, partly because I try to use POD and comments for separate purposes.

Chumley

Imagine a really clever .sig here.

[ralphie]

where i work, i'm the only person who uses perl. (i even get some of those strange looks ... ). i've adopted the strategy of documenting internally to the point that sometimes i think my code most resembles that in a tutorial. i suspect that my context is more like the real world than many, my rationale is that if someone else were to be forced to take responsibility for what i've done, i want them to be able to do so almost without knowing the language.

i think that ultimately the nature of the organizational environment might be the prime determinant. if your work would ultimately be maintained by perl cognisceti, your requirements are likely going to be different than if it were to be handed to a vb programmer.

[archen]

Although I do comment complicated things, I actually tend to use comments to tag what happens in blocks of code. I generally find that comments end up being really redundant to anyone with a fair ammount of experience. Thus I tag blocks so I can just read the block comment header to find if that is the section of code that I want to look at.

And yes, that's a bad way to do it! With Perl I think more comments are better, unless you start commenting things like


$i++   # incrament i

[dws]

Comments have to maintained, too. And quite often, they aren't. The result is a program that lies to the reader. The greater the proportion of comment lines, the greater the risk that someone downstream will break the comments while extending the code. Broken comments adds to downstream risk. Broken comments also add to the risk that the reader won't trust any of the comments, which further burdens maintenance efforts.

This is one of the forces that needs to be balanced in order to find the right mix of comments to code.

The eXtreme Programming folks take an extreme view on comments. They hold that comments are one of theCode Smells that are clues that your code has problems. If you need to write lots of comments, it's an indication that your code isn't clear enough, and that you should put effort into cleaning up the code so that it describes itself.

(This is a point on which reasonable people can differ.)

[tilly]

Well my opinions on comments seem to be an extreme around here. But read the entire thread starting at Re (tilly) 2 (disagree): Another commenting question, (and keep in mind that behind the scenes we were exchanging much more pleasant /msgs) to see my personal style laid out.

In there I lay out in quite a bit of detail my opinions on ways in which commenting can be negative, what needs comments, what does not, and how to comment. As you will see reading that, the question isn't really the density of comments. It is instead what do you comment, why do you comment, how do you comment, and in what ways do you make your code descriptive?

[LD2]

I don't think there is anything wrong with too documentation, if anything... there is something wrong with too less documentation (I know, bad grammer.. but you get the gist). Documentation doesn't slow code down - but it does make it understandable to those who must follow in your footsteps later to maintain it. Even if you maintain that code, months later you may forget exactly what you're trying to do in a certain function or whatnot - and documenation helps trigger the memory or explain it completely. Although many programmers detest documentation or documenting their own code - it's something that they're rather thankful when inheriting a project. It doesn't take too much effort and it saves time down the road... here are a few other nodes that have talked about documentation. Check out use documentation; and Danger, danger Will Robinson (documenting code).

[FoxtrotUniform]

When I started my current job, I'd put block comments everywhere in my code, saying what assumptions I was making and what was going on. Now, I've been moving away from gratuitous commenting: it's better, I think, to make the code speak for itself than it is to write bad code and tell the reader what it's supposed to do. (When that code changes, the comments usually get left out of date.)

My strategy now is this: write code to be as obvious as possible, and comment what's left over. Telling the user that &validate_foo validates a foo's value isn't especially useful, but saying that it expects a single reference to a foo is, for instance.

Update: Now that I think about it, &validate_foo is a horrible name for a subroutine, since it gives no clue as to what it returns. &is_valid_foo makes much more sense. (Although if having an invalid foo running loose in your code is a fatal error, then &validate_foo might just die or croak if the foo it was passed is invalid; if so, it should damn well be documented.)

--
:wq

[hsmyers]

I suppose that it depends on what you think the comments are for. If they are for someone else, it makes sense to expand accordingly. If for yourself, write as much as you need to remind yourself of what you were doing (thinking etc.) when you wrote the code in the first place.

Over the years I've noticed that I've become a little bit schizophrenic about documentation. For example, the first thing I do when evaluating someone elses code is to create a copy without comments at all. I'd rather see what the code is doing without being distracted by what the author thought it was doing! On the otherhand, I prefer to code using some form of Literate Programming (see Knuth) whenever I can. I think that this kind of contradiction demonstrates that this is a hard topic!

hsm

[toma]

At a minimum, each file should have:
1. A one sentence explanation of what the code in the file does
2. The name of the author
3. A date
4. Some sort of copyright

Some sort of version is also important, but often this comes from an external revision control system.

The most important code comments explain the known defects, limitations and the problems in your code.

Comments tend to say what you hoped your program would do. Just when you need the comment the most, it lies!

When I am tempted to write a comment to explain something, I try to reformulate the comment into an error message. I use something like the or die idiom used when opening files. This gives me nice a spot to put my description of what is going on. It is also easier to maintain. If the this doesn't seem natural, I put in a diagnostic print statement with a trailing if $verbose.

something_tricky() or die "Failed to execute the trick";
print "So far I have $my_intermediate_result" if ($verbose > 0);

It should work perfectly the first time! - toma