Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

Re: On comments

by eyepopslikeamosquito (Chancellor)
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?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (6)
As of 2020-02-18 09:09 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    What numbers are you going to focus on primarily in 2020?










    Results (75 votes). Check out past polls.

    Notices?