Dear fellow monks,

The past months, we have had a few (nice) threads about commenting source code. Methinks most can agree when I say it's an important issue.

In "Code Complete" by Steve McConell, there is quite a bit written on commenting. One technique that was explained, was that of PDL: 'Pogram Definition Language'. I gave it a try, and it worked quite well for me. I would love to hear your opinions of it.

I didn't read docs about PDL, just what McConnell had to say about it. To me it is straightforward: describe in simple terms, simple logic what your program does without using any language-specific idiom.

I tried it with one script I needed to create (you can find it here). Let me illustrate one subroutine: 

 =head1 $a = interval( $source, $interval, $number_bins)


Calculates inter-event interval histogram of the source (arrayref). Th
+e
$interval gives the maximum inter-event interval that should be counte
+d. The
$number_bins denotes the number of bins of the interval.


=cut


$PDL = <<'_PDL';
_interval_
extract arguments
prepare
return empty histogram unless the source has more than two items
get the first item of the series as a reference
walk over series
  assign current item to reference
  calculate difference between item and reference
add the buffer to the histogram
return the histogram
_PDL


sub interval {
  my $source = shift;
  my $interval = shift;
  my $interval_bins = shift;

  my @times = @$source;
  my $start_time = $times[0];
  my @interval_histo = (0) x $interval_bins;

  return \@interval_histo unless scalar(@times)>1;

  my $prev = shift @times;
  my @buff = map { my $time = $_ - $prev; $prev = $_; $time} @times;

  buffer2histo( \@buff, \@interval_histo, 0, $interval, $interval_bins
+ ) if scalar @buff;

  \@interval_histo;
}

[download]
McConnell said to copy the PDL as comments into the code, but to my personal opinion that gets unreadible. I think it partly is because perl is a very dense language, that explains itself to some extent. But the PDL provides something different, the logic minus language specifics.

PDL served me very well for the first draft. However, I needed to change some logic in second instant. During that rewriting stage, I just ignored PDL until I had it right. Only than I added new PDL for the changed routines. Afterwards, I changed some lines, as writing the PDL made some logic decisions more clear.

Are there any issues when using PDL for perl? Comments, thoughts, ideas? I'd love to hear them.

Jeroen
"We are not alone"(FZ)

Replies are listed 'Best First'.
Re (tilly) 1: Commenting: What about PDL?
by tilly (Archbishop) on Apr 10, 2001 at 03:34 UTC
    My experience with PDL is that it is a great way to produce code, but not to maintain it. Also I find in Perl that it works better to, instead of turning the pseudo-code into comments, turn it into function names. or Perl.

    I agree with you that things are changed somewhat because Perl is already a high level language, so the gap between what you are trying to do and how you do it is narrower than it might otherwise be.

    Should you wish to go the other way and make PDL into comments, you will wind up with densely commented code. While you had a good experience with updating it (largely because you chose to also update the comments) it doesn't age so well. This time around you likely left some comment in there which does not quite match the code. Or if someone else edits it they will. Add a few rounds of that and the comments will inevitably drift out of sync...

[reply]
Re: Commenting: What about PDL?
by Malkavian (Friar) on Apr 09, 2001 at 20:23 UTC
    This seems to pretty much be "Pseudo Coding", where you use plain language to step through what a program should be doing before you code it.
    I usually do that for code that can't be hacked out in an afternoon, or when many processes are involved. I tend to find it helps as a mid ground between plain hacking and software engineering (using UML, VDM, Z et al).
    Adding a section to the program is very useful, although, for most things, I embed it in POD, as it saves time looking for it in code. Just pod2text, or whatever takes your fancy, and there's a section describing the workings of the code.
    For coding the thing, it's a minor aid. for maintaining it (especially if you're not the coder), it can be an invaluable aid.

    Cheers,

    Malk
[reply]
      Thanks Malkavian,tilly for your thoughts.
      I haven't heard about Pseudo Coding yet. PDL is described in an official document cq book (McConnell provided a reference).

      I can see where it is a mid-ground. Even for the above afternoon-hack it was worth the trouble.

      The PDL didn't make it into the POD, as my module as public as well as private routines. I don't want the description of the private part in the docs.

      It is true that the PDL/pseudo code gives the maintainer a valuable insight into the code. However, tilly has a point about the maintainability of the PDL. It's low.

      Interesting. Your two opinions are totally orthogonal. Malkavanian find it invaluable in the maintaining stage, while tilly says it's handy when coding, but a disaster for the maintainer, as it probably contains errors.

      Maybe the following would work: Whenever a routine is changed in the maintaining phase, the maintainer uses the PDL, and than deletes it. After he is finished coding, he writes the PDL from scratch, or leave it empty.

      Would that be something?

      Jeroen
      "We are not alone"(FZ)

[reply]
        Actually the opinions are not quite so orthogonal as that. I would agree that initially maintainance will be very much helped by the PDL comments. However they won't age so well. As a result experienced programmers are likely to instinctively distrust those nice beautiful comments.

        This ageing process is not instantaneous, it is a creeping issue that comes over multiple rounds of aging. There is no clear point at which you know that the comments are now bad, it is a gradual process.

        Which is why I suggested making the pdl into function names rather than comments. Because function names are active code, are likely to get maintained with the code.

[reply]

Back to Meditations