Re: On comments (Commenting and Documentation References)

[eyepopslikeamosquito]

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

• Separate user versus maintainer documentation.
• Generally, comments should describe what and why, not how (strive to make the code obvious).
• Include a comment block on every non-trivial method describing its purpose.
• Comment any code that is likely to look wrong or confusing to the next person reading the code.
• Don't optimize prematurely. Benchmark before you optimize. Comment why you are optimizing.

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

References Added Later

• On Interfaces and APIs
• On Coding Standards and Code Reviews
• On Code Optimization
• Writing Solid CPAN Modules

• Where to place POD by Bod (2024)
• More comprehensive style guide for Perl docs than perlpodstyle? by nysus (2019)
• What's your programming style? by harangzsolt33 (2018)
• documentation best practices for internal modules by hotshoe (2018)
• Tools for annotating module code? by nysus (2017)
• Re: Modern Perl: The Book: The Draft (feedback) by me (2010)
• On comments by permungkah (2010)
• Programming *is* much more than "just writing code". by BrowserUk (2007)
• flower box comments by mandog (2003)

Updated: Reorganized the bullet points; extra references were added later.