Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Re: How to write long programms?

by jynx (Priest)
on Mar 08, 2001 at 06:28 UTC ( [id://62902]=note: print w/replies, xml ) Need Help??


in reply to How to write long programms?


People have already written that one should comment, but i would like to make an addendum to that:
Comment well.

Bad comments are worse than no comments at all. Some areas need heavy commenting because they do the black magic of the program. In these cases, it's usually better to type up a well-written paragrah (in full english) that explains why the section does what it does and how. Then post that paragraph above the black magic and make sure it's noticeable and easy to read (using various commenting styles to make it obviously important)

As a general rule of thumb, if you can't comment it well you might reconsider how you're approaching the problem that the code solves. i've had to reinvent a code section three or four times on one program just because i couldn't describe why i did it that way that made any sense.

And lastly, to make sure that beautiful paragrah makes sense, see if a co-worker or pedestrian (hopefully with no knowledge of that section fo the program) can read and understand what you're trying to do. If they can, then when you go back and read it 2 days later, you should also have no problems.

This is just my experience, YMMV, HTH,
jynx

PS If it takes more than a paragraph to describe some code, maybe you're doing too much with that section, it might needs be split up, maybe...

Log In?
Username:
Password:

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

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

    No recent polls found