My thoughts:

• Comment for two people: the person you want take over your code and one person in the whole world you would most hate to maintain your code.

• If you use something "elegant," document it. Either in comments or supporting material.

• If you use something taken from somewhere else, cite it and make sure copies are saved in the project folder.

• Explain the idea, not the action. I can tell that a loop increments or sets certain values. I may not know why that's necessary.

• Document business rules and data structures very carefully. Discuss requires relationships, indices, validations, ranges, and dependencies.

• Explain the purpose of your programs, your subroutines, and how variables are intended to be used. Include discussions of non-supported parameters, values, and data types.

• Carefully explain hacks and workarounds, just in case the problem being worked around eventually gets fixed.

• Describe build processes and dependencies very carefully...just in case your manager (or an intern) needs to re-compile after you've left.

• Update your comments as you maintain your code.

• Spell check your comments and fix typos.

• Include contact information as appropriate. If it's a business project, include telephone numbers and email addresses of the development manager and the project sponsor.

• Cross-reference to other documentation as appropriate. If there's a specification, refer to it. If you're fixing a bug, include the bug number, your initials, and a very breif description of what was changed.

When finished, ask yourself if you would find the available information adequate if you were handed the project cold, off the street. If not, you need more.

I've mentioned previously that I tend to over-comment. However, I believe that far too much information is lost during the development of a project. Information that must be re-discovered during each development phase. This unnecessaily increases the cost and burden of maintenance. A 1:1 ratio may be extreme to some, but it's better than 0:1.

Keep in mind that it's very easy to keep a text editor open while you're coding. Use this to collect tidbits for external documentation.

--f

Update: danger pointed out that I accidentally wrote "too little" when I meant "too much." Oops.... :-} Fixed.

---

---

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.