Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
Good commenting can:

What about s/Good commenting can:/Good coding can:/ ? And that's the main point.

  • make you describe what is intended.

    That can, and should be done with code proper.

  • make you to consider edge conditions and check that cases that need to be covered are covered. You should do that anyway, of course, but if you write it down it's more concrete.

    What is better than code which considers edge conditions, naming the conditions by proper set branches and variables? The requirements are (or should be) in the specs. Code is no place for that.

  • require you to express and examine assumptions

    that is what we do all time along coding perl. Anything which can't be done that way needs to be cleared beforehand and laid down in the specs.

  • justify and document the choice of algorithm or method.

    The choice of algorithm is done per knowledge. Now, you wouldn't document your knowledge in any (every?) piece of code you write, would you? Algorithms can be named, if they have a name. If they work out to the specs, that's fine. If they don't, they are changed, and describing the "why and whence and how" sayings doesn't add anything to the comprehensiveness of the code. The code should be written to be comprehensive in the first place.

  • leave notes on things which were not obvious when you worked out what needed to be done or how to do it

    This is the only reasonable item in the list - quoting Kernighan: "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."

    Teaching perl, the first code samples of your pupils are like that:
    open my $h, '>', $file # try to open a file or die "Can't open '$file' for writing: $!\n"; # if that fails, te +rminate with a message while(<$fh>) { # reading a line via <$fh> assigns per default +to $_ s/foo/bar/; # s/// operates per default on $_ }
    That's okay, since they want to remember what they have learned. Maintaining code and refactoring is a totally different issue. If you do that, you have to toss around code, and having comments piggyback is - piggyback, and a burden. If every EXPR is written properly; if every STATEMENT is clearly written; if every BLOCK defining a SCOPE containing STATEMENTS which are comprehensible on their own, or as part of the enclosing PACKAGE, or APPLICATION to which they apply, everything is fine.

I choose to code in perl (also ;-) because that way I have a wealth of expressions at hand which makes - or could make, if I work up to my level of experience - the code self-explanatory. And that's the goal. Anything below that can only be badly mended with comments. They are workarounds. Your program is a technical paper, which should be readable on its own by technicians of the same craft, but not necessarily for pupils (unless you are a teacher) or laymen. Those technicians which can't need teaching (by themselves, or training by somebody else), and that fact cannot be mended with comments either.


In reply to Re^2: Why no comments? by shmem
in thread Why no comments? by targetsmart

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 drinking their drinks and smoking their pipes about the Monastery: (4)
As of 2024-04-25 09:01 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found