Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Re: Another commenting question,

by japhy (Canon)
on Mar 15, 2001 at 23:31 UTC ( [id://64759]=note: print w/replies, xml ) Need Help??


in reply to Another commenting question,

At my job, we recently started a style guide for our code. One point of order is the documentation we put in our code. We are putting Pod in all our modules, and even some of our CGI programs (that accept an insane number of CGI parameters).

In addition, we are moving towards commenting blocks of code, to increase readability, and to keep everyone on the same level -- just because I wrote the code doesn't mean the guy next to me will never touch it, or maybe even modify it.

But documenting your code line-by-line is not efficient. If you have to do that, you're not using descriptive variable and function names. They have names for a reason -- you can give them names that fit their functionality.

One of the most informative comments I wrote today was an ASCII depiction of two images I was creating with GD. The variable names are helpful, but it's difficult to get a grasp of what the coordinates mean without some graphical representation of the figure:

# draw a skewed rectange for each data-point # ____ # G p D \ # / o / | | # B_t_C | | # | | +-- $val_height # | face | | # | | / # | E \ # | / +-- $slant_height # A____F/ / # # \-+-/ \+/ # | | # $ppd - $consts{slant}
And then I went on and used those alphabetic labels when I created the polygons:
if ($params->{dim} == 3) { my $face = GD::Polygon->new; A: $face->addPt($x_pos, $yi + $val_height - 1); B: $face->addPt($x_pos, $yi + $slant_height); C: $face->addPt($x_pos + $ppd, $yi + $slant_height); D: $face->addPt($x_pos + $ppd + $consts{slant}, $yi); E: $face->addPt($x_pos + $ppd + $consts{slant}, $yi + $val_height - +$slant_height - 1); # E F: $face->addPt($x_pos + $ppd, $yi + $val_height - 1); $image->filledPolygon($face,$hist_front{"@$cRGB"}); my $top = GD::Polygon->new; B: $top->addPt($x_pos, $yi + $slant_height); G: $top->addPt($x_pos + $consts{slant}, $yi); D: $top->addPt($x_pos + $ppd + $consts{slant}, $yi); C: $top->addPt($x_pos + $ppd, $yi + $slant_height); $image->filledPolygon($top,$hist_top{"@$cRGB"}); }


japhy -- Perl and Regex Hacker

Replies are listed 'Best First'.
Re (tilly) 2: Another commenting question,
by tilly (Archbishop) on Mar 16, 2001 at 00:20 UTC
    The single most useful comment that I can remember making, which was tied to a surprisingly well-named pair of variables that just happened to look awful, was, THINK CARTESIAN! x and y represent Cartesian coordinates. Keep that in mind and all will make sense.

    Whenever I tried to describe what I was doing in the code in words, I failed. But with the picture in hand it was dead obvious how to manipulate the grid. :-)

      Whenever I tried to describe what I was doing in the code in words, I failed.

      Just want to share my 0.3 Euro (2 cents) advice, someone once tell me :
      "Never tell what you're doing in your comments, as you should make it obvious in your code,
      instead say what is your goal and why you're doing it this way (special cases and constraints)"


      "Only Bad Coders Code Badly In Perl" (OBC2BIP)

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others musing on the Monastery: (6)
As of 2024-03-29 01:07 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found