Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

Re: The art of comments: (rave from the grave)

by Limbic~Region (Chancellor)
on Jul 07, 2005 at 20:08 UTC ( [id://473214]=note: print w/replies, xml ) Need Help??


in reply to The art of comments: (rave from the grave)

BrowserUk,
95% of the code I develop is written for monks here at the Monastery or for strangers on #perl in IRC. I almost never comment code and very rarely receive questions as to how the code works. I think this because of a handful of reasons:

  • I use variable names that aid in understanding the code
  • I use function names that aid in understanding the code
  • I present the code in small digestible chunks
  • The person reading the code already knows what it is supposed to do and only has to figure out how

There are a few instances when it has been necessary to comment my code. This is either because the approach to solving the problem is not obvious to the individual seeking assistance or because their level of competency warrants them.

This is not to say that everyone reading the thread is able to understand it as there are rare occasions when clarification is requested. The best example of my own commented code I could find was that of Perl6 and are probably mostly superfluous due to the text description, which is what POD is for afterall.

Cheers - L~R

While my one public module is documented using POD, it does not contain comments.

Replies are listed 'Best First'.
Re^2: The art of comments: (rave from the grave)
by BrowserUk (Patriarch) on Jul 07, 2005 at 20:42 UTC

    Limbic~Region. In part, my reason for asking for links of what people found to be good examples was an attempt to discover whether anyone ever found somebody elses comments good, rather than just their own (idea of what would make) good commenting.

    My own contention is that:

    1. many people have high ideals with regard to commenting.
    2. these rarely coincide.
    3. almost noone sticks to their own ideals.
    4. almost noone has ever seen an exampe of someone elses commenting that (sufficiently) complies with their own ideals for them to hold it up as an example.
    5. that even those rare pieces of code that start out containing good commenting, lapse into the melee of unmaintaind, out-of-date, and irrelavent over time.

    That's not to say that there aren't good uses for comments. Just that over time, they become less good.

    Personally, if find it easier to write the code than a (good) comment about it.

    Historically I've found that if I don't understand the code, the associated comments rarely help and often hinder. Indeed, if I want to work out what a compex piece of code is doing, especially if it is my intention to modify that code, I found that deleting the comments and reading the code is the only way (for me).

    Occasionally, if the commenting is detailed enough, it serves to show up a distinction between what the author thought they were coding and what they actually coded--which I guess serves a purpose, but any commenting that is detailed enough for that to be true, will usually be described as "over-commented", even by those that encourage commenting.


    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
    "Science is about questioning the status quo. Questioning authority".
    The "good enough" maybe good enough for the now, and perfection maybe unobtainable, but that should not preclude us from striving for perfection, when time, circumstance or desire allow.

      I'd agree with this: I rarely include comments in my own code (though I put a lot of effort into making the code itself self-documenting). Similarly - and maybe because of this - I rarely look at the comments when looking at other people's code, and find it a substantial hindrance if there are too many, or if they are placed in such a way that it is difficult to look past them at just the code.

      Hugo

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others goofing around in the Monastery: (9)
As of 2024-03-28 11:53 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found