Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister
 
PerlMonks  

Re: What is your practice for code documentation?

by Erez (Priest)
on Jun 26, 2008 at 07:50 UTC ( [id://694119]=note: print w/replies, xml ) Need Help??


in reply to What is your practice for code documentation?

I prefer good, well structured, clean, and cohesive code to the best comment any time. Perl, which is, to me, a language that is structured as a spoken language (assuming we would speak in routines, loops and variables), shouldn't (theoretically) be commented more than the obligatory synopsis, the API, and the overall i.e. the "man". If you have to explain anything beyond the overall things, you may need to rethink your code, not your comments.

If your code needs a comment to be understood, it would be better to rewrite it so it's easier to understand. (Notes on Programming in C - Rob Pike)

(Oh, and "hits the argument on the head and drives it right home"?)

Stop saying 'script'. Stop saying 'line-noise'.
We have nothing to lose but our metaphors.

  • Comment on Re: What is your practice for code documentation?

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://694119]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others pondering the Monastery: (None)
    As of 2024-04-19 00:00 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      No recent polls found