Jeroen
"We are not alone"(FZ)

I have read Code Complete, and I agree it raises some good points,
but seeing as I don't know Pascal (which most of the examples are in)
I find reading the book really frustrating.
I wish he would update the book with some examples from Perl and Java.

UPDATE:
Maybe explaining what I meant would be good, since I am still get voted -- on this
ack!

I think that what Code Complete has to say regarding commenting, and construction of code to be well said, and
still applicable.

But there are portions of the book, especially Design, where the material Steve McConnell presents
feels dated to me. I don't know Pascal, so talking about the merits of it as a language in his examples
does not elucidate his discussion.

Further, Steve McConnell spends a long portion of his discussion in design talking about modules, when I prefer functions.

Basically I rubbed some people with my opinion and if I did, so be it. I'll take my drubbing, but it's my opinion
and I'm not going to change it because this book holds a revered place in some people's libraries.

I still wish he'd update his examples with some from Java or Perl.

I like using pre- and post- conditions a lot of the time. The subroutine should say what it expects, and under what conditions you get a return value, etc. Something like:

sub add_one_to_number() {
  # add_one_to_number ($number) : takes a number, returns number + 1
  # PRE1:   number exists
  # POST1:  we return the number plus one
  my $number = shift;
  if (! defined $number) { 
    return undef; # fail PRE1
  }
  $number++;
  return $number; # success POST1
}
[download]

Okay, Noddy example, I know. It marks out under what conditions the author expected to reach these areas. If there is a bug at all, either it's because there is a precondition that we haven't thought about, or we don't successfully reach the postcondition (i.e., incorrect code). Also, putting in carps and things helps you track better what's going on if you follow the PREs and POSTs.

It's one of the things that works for me, anyway :) (obviously, this is in addition to all the other comments and stuff you make!!)

I try to adhere to the following rules:

Use a self-explaining name for the sub, this will also explain the return value(s).
Use self-explaining names for the parameters, they are pulled in at the top of the sub, so they are seen immediately.
For subs used outside of the modules use pod.

Or Robodoc, which should work with perl too.

Have Fun

Since I also use CVS for my source code control, I have also gotten in the habit of, at the very bottom of the POD, to create a HISTORY section and putting a $Log$ tag in there. It keeps the checkin history with the file, but doesn't clutter either the top of the file or r the POD with a lot.

I also have written code similar to yours to pull my sub headers out and marginally PODify them. Check out this node for one of my more interesting attempts ( the first toy ) at documenting the possible return values for a module.

mikfire

###################
#
=pod

=item displayform

Usage:
      displayform( ['message to user']);

Displays a form for the user to fill out for submission
to ARS Server. Required field for the form is 'problem'
(body text).
There is an optional string parameter to this function
that will display a message along with the form.

=cut
#
###################

sub displayform {
...
[download]

#Requires:
#          var 1 to be valid <something>
#          var 2 to be valid <something>
#
#Returns:
#          var 1 is Preserver/Produces/Destroys
[download]

#***<StringToArray>*************************************************
# Purpose: Combine 2 strings into 1 array
#
# Inputs : 2 strings
#
# Outputs: 1 array
#
# Programmer         Date        Comments
# ---------------    --------    --------
# Bob Smith          03/30/01    Created
#******************************************************
[download]

Edited Wed Oct 17 23:37:54 2001 - Footpad

I think that even more than other programmers, Perl people have to take most care to write clear code.

Perl code, with heavy use of RegEx, default variables, and syntax trickery, can be an absolute pig to read (all you one-line-coders, take note!). Code readability has to be one of the most important aspects of professional programming.

And it's all very well making a commitment to comment all your code, but the more comments you add, the harder it becomes to maintiain your code. Either you spend too much time adjusting comments when the code changes, or you don't update them at all: (excuse the Java example)


public String getCustomerSSN()
{
    // return the customer's SSN<
    return customerSSN;
}
[download]

becomes:

public String getCustomerID
{
    // return the customer's SSN
    return customerID;
}
[download]

...so the comment (which was already not really necessary) becomes incorrect, making the code less clear.

A good example of code that can be relieved of comments:


if (ftpResponse.charAt(0) == '2')
    // ftp result in 200s = success
[download]

if a method is added to do this test:


public boolean wasSuccessful(String ftpResponse)
{
    return ftpResponse.charAt(0) == '2';
}
[download]

...then the original code becomes:


if (wasSuccessful(ftpResonse))
[download]

...so the comment is no longer necessary.

(The above examples come from 'Essential Java Style' by Jeff Langr (Prentice Hall PTR) - a very good book that goes through a series of Best Practise rules-of-thumb. In this case, he goes on to say that one of the few places where comments are necessary is when a method has a dependency, i.e. it requires that another method be executed first.)

I know from personal experience that excessive comments can ruin productivity - on one of my first commercial projects, the head programmer insisted that everyone had a ratio of about 2:1 comments to code (that's two lines of comments per line of code!). The design sucked, so despite all these comments the coding was difficult, unclear and underproductive.

On the other hand, when I worked on a project six months later, using the Extreme Programming methodology (XP), where you are supposed to have practically no commenting, we were writing excellent safe code. One of the idealogies of XP was that code always should be as simple and clear as possible. If it could not be easily understood, it was basically wrong.

I don't want to sound like a Software Engineering lecturer, but I certainly want to say that (IMHO) if a problem is unclear, you really, REALLY should not jump in and start coding it. An extra hour spend dealing with the more abstract design will save you 10 hours in coding, maintainance and debugging, and a good design will make any problem more clear...

(waving goodbye whilst dismounting my high horse)...

first off, let me say that i do not disagree with you.
that said, i would like to clarify. i was not refering
to a problem unclear in that i did not understand. i was
describing the fact that sometimes the logic needed for
solving a problem is not obvious, is not intuitive, and
quit often is not any clearer than mississippi mud. these
are the times when after you understand the problem, you
can step back and see the issue still resides in a fog
bank, but rather than spend all day looking for a nice
little way to code so that your little sister in elementary
school can understand it, you bang in a quick and dirty
line that solves the problem and a nice descriptive
comment to enlighten your posterity.
in response to the 2:1 ratio... that's called 2 weeks notice
in my book. insanity is not my cup of tea, and that is
clinical right there. if you have not come across a problem
that requires ugly logic, you have not experimented much.
i also fall heavily in support of the "hacker ethic" described
so well by steven levy in "hackers - heroes of the
computer revolution" in that any code you can write,
i will write in less lines. (not a challenge, just
philosophy) "bumming" out instructions
is the foundation of computer programming and continues
to drive me as a programmer. if i write something, i
will write it later in less lines. i do not ask you to
agree, but i ask you to not insinuate my "more functionality
with less keystrokes" method is wrong. i do not argue
that you are wrong because you like to write in cute
little snippets with no comments, so please extend me
the same curtesy. thanx, and my what a beautiful horse
that was.

Shadowfax

"A computer is almost human - except that it does not blame its mistakes on another computer."

// ========================================================
//       COUNT OCCURRENCES (
//                          STR, // String to search through
//                          SUB  // String to search for
//                         )
// --------------------------------------------------------
//   Counts the instances of SUB in STR. Counts overlapping 
//     occurrences.  Count_Occurrences( 'rrrrr', 'rr') = 4.
// --------------------------------------------------------
function Count_Occurrences ( STR, SUB ) {
 var last   = 0;
 var count  = 0; 
 while ((last = STR.indexOf(SUB, last + 1)) > -1) { count++ }
 return count;  
}
[download]

-Lexicon

ouch! you just hit on one of my pet peeves... bad spelling.

It's "occurrence", not "occurance". Your code may be the greatest thing in the world since sliced bread, but if routine names contain spelling mistakes people are going to believe that the code contains other shoddinesses, thus you wind up needlessly damaging your reputation.

Worse, client programmers using your code are going to stumble and trip, because they're going to try and call count_occurrences and fail miserably.


--
g r i n d e r