Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation

Re: Why no comments?

by GrandFather (Sage)
on Jan 31, 2009 at 11:02 UTC ( #740404=note: print w/replies, xml ) Need Help??

in reply to Why no comments?

Writing good comments is at least as hard as writing good code. Bad comments can be worse than bad code. Comments can give the reader the impression that they understand the code without the need to actually read and understand the code. If the comments are good, that's fine. If the comments are bad that can lead to a great deal of wasted time and frustration.

Don't get me wrong. Comments are an important part of writing good code. But it is better to write good code that speaks for itself than to write a translation of the code into some semblance of English (or whatever language is appropriate).

Good comments convey the intent of code and may explain how a tricky algorithm works, but doesn't give a blow by blow description of the code.

Modules provided by CPAN are written by people of vastly varying ability and can demonstrate code on many different levels, but few of those modules are written for their educative value. "Dumbing down" a module so that it is accessible to learners doesn't help CPAN and doesn't actually help learners. For one thing, there are much better ways to learn Perl basics (PerlMonks for a start), and for another: learners don't stay learners for ever, so what level should the comments and code be aimed at?

Comments in code for CPAN should be designed to ease the job of maintenance programmers. Generally that means few comments and much thought given to appropriate coding, identifiers, documentation and test suites.

That is not to say either that there isn't a lot to be learned from reading CPAN code. There is a great deal that can be learned from examining CPAN code. But you shouldn't expect it to be entry level stuff.

Perl's payment curve coincides with its learning curve.

Replies are listed 'Best First'.
Re^2: Why no comments?
by doom (Deacon) on Feb 01, 2009 at 21:54 UTC

    If the comments are bad that can lead to a great deal of wasted time and frustration.
    This is a very common attitude, and I suppose it must reflect someone's experience, but it doesn't reflect mine. My experience is that even when the comment is in error it gives you a hint about the history of the code, the state of mind of the author, and so on.

    It's a basic skill of reading, if you ask me: you can't take anything at face value, but it doesn't mean it's worthless, either.

      you can't take anything at face value

      That statement is not true about code. If you compiler isn't buggy, the code does exactly what it says it does. And it's the whole reason why code is more important than comments.

      During bug fixing some time ago I came across a comment that was plain wrong - it described the effect of the code as being the opposite of the actual effect. After spending considerable time "fixing" the code I discovered that it had in fact been correct and that the bug I was looking for was in a completely unrelated piece of code.

      In that particular case there was no need for the comment. One reason the code took considerable time to "fix" was that all the identifiers were "wrong". Without the comment the code was correct, consistent and clear. However, the comment was plausible and in the context of the symptoms of the bug the code could well have been incorrect.

      Perl's payment curve coincides with its learning curve.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://740404]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others surveying the Monastery: (9)
As of 2019-10-15 03:53 GMT
Find Nodes?
    Voting Booth?