Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical

Re^3: Code Maintainability

by doom (Deacon)
on Dec 07, 2008 at 00:02 UTC ( #728617=note: print w/replies, xml ) Need Help??

in reply to Re^2: Code Maintainability
in thread Code Maintainability

I've never had to work with one of the legendary "comment every line" types -- it could be they don't get hired at the kind of places I've worked.

From skimming tilly's example here: [Text::xSV] I would summarize that he likes sparse, higher-level comments, but with very verbose error messages that actually function fairly well as substitutes for comments. At a glance it does seem that both variable names and sub names are a bit short, but then, they don't strike me as confusing. He also likes pod-at-the-bottom style which also comes recommended by Conway in his "Best Practices" (I'm a fan of interspersed-pod style, myself, but not so much that I'd insist it's the One True Way).

By the way: if the main objection to comments is that they tend to diverge from the code, what does one do about those rather infrequently run error messages? Don't they, too, tend to diverge from the code? And what about the the "=item" lists buried down in the pod?

Anyway, as it happens, I've written up a brief comment example: Re^5: Programming *is* much more than "just writing code". In summary: explaining a paragraph of code in english can speed skimming through the code, and hinting at how a line of code works can sometimes be a good idea.

Replies are listed 'Best First'.
Re^4: Code Maintainability
by tilly (Archbishop) on Dec 08, 2008 at 03:01 UTC
    My variable and function names are now longer because I found that I used to shorten them inconsistently.

    Errors are tested in my unit tests. If the logic leading up to the error message is wrong, I should notice that there.

    Errors in POD are an issue for manual review. I do not claim perfection, and my error rate there is higher than elsewhere. But knowing that, I know to focus more attention there and so can catch a lot of those bugs.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://728617]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others meditating upon the Monastery: (6)
As of 2018-06-20 15:43 GMT
Find Nodes?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?

    Results (116 votes). Check out past polls.