Re: Nice clothes (Term::ProgressBar, perltidy, Getopt::Declare)

What makes it pretty? In my opinion, it's about maintainability. For me, a well-formatted comment block at the beginning, chock full of info; inline descriptive comments; well-chosen variable names; and some good man page POD added after the __END__ make for what I think is "pretty".

Even if the algorithm is inefficient, the copious documentation and notes should allow for someone to "upgrade" it in the future. Admittedly, using a well-defined interface would help allow user-transparent upgrades.

-v

"Perl. There is no substitute."

Comment on Re: Nice clothes (Term::ProgressBar, perltidy, Getopt::Declare)

Replies are listed 'Best First'.
Re^2: Nice clothes (Term::ProgressBar, perltidy, Getopt::Declare) by tilly (Archbishop) on Aug 08, 2004 at 07:55 UTC
One disagreement. Copious documentation in my experience tends to become bad documentation. Documenting everything leads to unmaintained comments that, over time, wise maintainers learn to ignore. Documentation needs to have a clear purpose, accomplish that purpose, and not attempt to do more. As I0 said a long time ago, I find the most useful comments state what remains invariant, while the code states what gets transformed. A past thread on this is Re (tilly) 2 (disagree): Another commenting question,. A couple posts into that thread you'll find a set of coding guidelines for when I do (and don't) comment, and why. I still pretty much follow that.	[reply]

Replies are listed 'Best First'.

Re^2: Nice clothes (Term::ProgressBar, perltidy, Getopt::Declare)
by tilly (Archbishop) on Aug 08, 2004 at 07:55 UTC

Copious documentation in my experience tends to become bad documentation. Documenting everything leads to unmaintained comments that, over time, wise maintainers learn to ignore. Documentation needs to have a clear purpose, accomplish that purpose, and not attempt to do more.

As I0 said a long time ago, I find the most useful comments state what remains invariant, while the code states what gets transformed.

A past thread on this is Re (tilly) 2 (disagree): Another commenting question,. A couple posts into that thread you'll find a set of coding guidelines for when I do (and don't) comment, and why. I still pretty much follow that.

[reply]