Re: Re: Commenting: What about PDL?

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)

Comment on Re: Re: Commenting: What about PDL?

Replies are listed 'Best First'.
Re (tilly) 3: Commenting: What about PDL? by tilly (Archbishop) on Apr 10, 2001 at 21:33 UTC
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]

Replies are listed 'Best First'.

Re (tilly) 3: Commenting: What about PDL?
by tilly (Archbishop) on Apr 10, 2001 at 21:33 UTC

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]