Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

Re: Commenting One's Code In A GNU/GPL/OpenSource World

by trs80 (Priest)
on Apr 01, 2002 at 13:23 UTC ( [id://155752]=note: print w/replies, xml ) Need Help??


in reply to Commenting One's Code In A GNU/GPL/OpenSource World

I think commenting code is important, but if I read between the lines and apply some of my own way of thinking I can agree with this post on the following merits:
  • The purpose or purposes of the code is still unclear in the developer mind, that is it is in very early stages. Commenting at this stage *can* influence someone into thinking that is all or only what the code can/should do.
  • I see over and over again, and I say it myself, that at some point in the future you will come back and look at the code and have to wonder what you did. I have to wonder if it is possible to influence your own corrections by reading your previous comments. I feel it is and I think it has even happened to me.
  • Skill level of the intended audience. Not commenting can be a way to keep (scare) "unskilled" people away from the code, this has its advatanages and disadvatages depending on whether you want your project to used for new coders to learn from or if you are producing something delicated and by not commenting hope to keep the casual user from "hurting" themselves.
  • My favorite reason (excuse): You have become enlightened and your knowledge of the code exceeds your impatience so commenting becomes a hinderence not an aid.
Ok so what about comments that *should* be in the code? The WHY you did that comment. I think these are far more valuable then explaining WHAT is being done. For example, in some resent code I was working on I had some trouble with rand not really being so rand so I looked up the function and read up and saw that I needed to add the srand function to get better results. I need to document the srand function call as to WHY I added it so that time isn't wasted on relearned by me or learning by someone else as to why the srand function is needed to correct a problem under a particular condition.

Commenting also adds to the learning process. When you comment WHY you did something you reinforce what you have learned and how you applied what you learned.

In short I agree with Revelation's argument if I interpet the type of commenting he wants to avoid correctly.

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others having an uproarious good time at the Monastery: (6)
As of 2024-03-28 18:45 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found