Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
In many ways this is a continuation to the Why my company doesn't use perl :( thread courtesy of ovid we had a while back because commenting code certainly is one of the things often implemented in a coding standard.

I code for myself at the moment, being a poor student, but I still comment my code fairly extensively using a standard of my own devising (see below) for a number of reasons -

First and foremost it is a good habit to get into: Much as surgeons, pilots and submariners have specific checklists that they adhere to even when such may not be strictly necessary (Here I make no claims as regards the quality of my code being to such a professional standard!) programmers should also develop such approaches. Get the habit and you'll keep it. If (when?) I end up coding as a job after University this will be one less habit to get into.

Secondly in situations where a programmer's code may be read by others it makes sense to give a general guide to your approach to the problem: This makes it easier on other who have to read your code and explains why you have done something in the particular way you have chosen. If other people do this too, you'll find it easier to learn from their code as the approach they have chosen may not be the one you would have taken: This is something you can learn from to improve your own style and breadth of coding experience. Also it will help in code reviews as the person doing the reviewing will have a handle on your method.

Finally, sometimes I don't get around to finishing a problem in the time I think I will: My workload can be quite heavy at times (Especially now, as I am studying in a foreign language and have exams every two to three weeks on average) so I might have to put somthing down for a week or two and the thought processes involved in the particular problem won't be simmering in the background as they often are when you're occupied on something. The comments help you to get back on track much more quickly if you've had to lay off something for more than a week or two.

Anyway, here's the way I do things:

  1. Three line summary: Just after the shebang (and use strict;) I give a three line summary of what the program is supposed to do and roughly how. I find that three lines usually is enough to give a general outline. For bigger scripts this can/should be augmented to five lines; any more and you should consider putting the details in a pod block at the end.
  2. Scalar names and use: This is a mixture of coding style and doculentation. Having a series of variables with names like olive, gin, ice and martini so you can say $martini = ($olive + $gin + $martini)/$ice; is very cute but can be pain in the arse to unravel. Give your variables sensible names and comment them when you declare them. Something like:
    my $logfile_name; #Stores name of logfile for appending my %user_logins; #Hash of logins indexed by username
    is probably the way I'd do it.
  3. Block comments: A one line comment for each for/while/foreach block to give the general purpose of the section.
  4. Scattered comments: If you are about to do something that can be done in either a number of ways, that is a hack, or seems strange, detail what you are doing and why. This can usually be fitted into three lines.
  5. Documentation: There is nothing more frustrating than seeing a module which doesn't have the details in the pod; methods names, parameters to pass etc... On the rare occasion that I write something bigger than a 100 line script I generally stick some POD at the end detailing the niceties of the script. Required CPAN modules is a must as is the version of perl needed.

In many ways you could think of commenting as being like the flow of consciousness as you write your code: It gives ideas as to what (the hell? ;-) you were thinking when you wrote that particular script.

Anyway, enjoy.

Elgon


In reply to Comments as flow of consciousness... by Elgon
in thread Another commenting question, by scottstef

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
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: (4)
As of 2024-04-19 13:41 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found