in reply to Commenting: What about PDL?
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
Re: Re: Commenting: What about PDL?
by jeroenes (Priest) on Apr 10, 2001 at 12:49 UTC
|
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] |
|