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)

In reply to Commenting: What about PDL? by jeroenes

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


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.