Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw

Re: On comments

by eyepopslikeamosquito (Bishop)
on Dec 20, 2010 at 01:49 UTC ( #877929=note: print w/replies, xml ) Need Help??

in reply to On comments

I agree.

My rules for commenting (from On Coding Standards and Code Reviews) are:

  • Correctness, simplicity and clarity come first. Avoid unnecessary cleverness.
  • If you must rely on cleverness, encapsulate and comment it.
  • Prefer to make the code obvious.
  • Don't belabour the obvious.
  • Generally, comments should describe what and why, not how.
  • Remove commented-out code, unless it helps to understand the code, then clearly mark it as such.
  • Update comments when you change code.
  • Separate user versus maintainer documentation.
  • Include a comment block on every non-trivial method describing its purpose.
  • Major components should have a larger comment block describing their purpose, rationale, etc.
  • There should be a comment on any code that is likely to look wrong or confusing to the next person reading the code.
  • Every non-local named entity (function, variable, class, macro, struct, ...) should be commented.
  • Don't optimize prematurely. Benchmark before you optimize. Comment why you are optimizing.
  • Limit and explicitly comment case "fall throughs".

See also Perl Best Practices, Chapter 7, Documentation, which has some excellent advice on how to document your programs.

Log In?

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

How do I use this? | Other CB clients
Other Users?
Others imbibing at the Monastery: (6)
As of 2021-02-28 16:00 GMT
Find Nodes?
    Voting Booth?

    No recent polls found