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

Replies are listed 'Best First'.
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]

In Section Meditations