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.

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.