Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses
 
PerlMonks  

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

by magnus (Pilgrim)
on Jul 07, 2005 at 09:06 UTC ( [id://473055]=note: print w/replies, xml ) Need Help??


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

As someone who has had to support 8,000 line perl scripts with single line comments every 300 or so lines in Italian, I can say that for me, more comments are better than less comments, in general...

I've found myself having to support so many other people's scripts (AWK, Shell, Perl, etc) that my most beloved comment is the "explination" comment block which basically states what the next block of code is supposed to do, why and even the expected output (an extra special point if they put in their thought processes)... I know for some, this is too much commenting, but when you are supporting a script that no-body's done anything with for two years and no-one has any idea of what was behind the programming, these type of comment blocks can save DAYS of rehashing, esp. if there are multiple calls to other scripts and exported veriables...
# # This next block was actually put in because # Joe Manager needed to see the output as a # webpage and not as a text mail. (Fair enough.) # The output (amid the html code) should look # something like: # # Logins User-ID Real Name # ------------------------------------ # 8 3rtulla Arthur Tulla #
My opinion is that good scripts are maintainable by people who know less than you about the code, don't want to learn (necessarily) to program in that language and need to update or change that script quickly. Good commenting is how this can easily be acheived.

okay, after re-reading this posting, i see it has a heavy sysadmin bent... my hand is revealed... =)

magnus

Replies are listed 'Best First'.
Re^2: The art of comments: (rave from the grave)
by cees (Curate) on Jul 07, 2005 at 15:18 UTC

    I like these types of comments as well, but I also find that lots of programmers tend lie in these comments. The comment may have been accurate at one point, but a small API change altered the behaviour of the function, yet the comment was never updated. I have seen this is my code (*blush*) as well as in others, and it can really throw you off.

    Here is a maxim that I usually go by: The farther away a comment is from the code it tries to explain the less reliable it is.

      yes, i agree... for me, it is a balance between updated code and updating/revising comments... and commenting blocks is trickier than lines, as, as you say, it can become fast impossible to tell just what is being commented on and what isn't... and too many line comments makes the code almost unreadable...

      magnus

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others avoiding work at the Monastery: (3)
As of 2024-03-29 15:54 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found