There is no such thing as too much documentation, no matter how redundant it may be. Lack of documentation is almost always wrong (programmers should not resort to sourcediving to learn function names).

Lack of needed documentation is always wrong - however over documentation, in my experience, can cause problems. For example:

• Excessive documentation/comments can be an excuse for poor code. Rather than spend the effort to produce comprehensible code certain developers will write a long and complicated piece of text to justify their technique. It sounds weird I know, but I've come across it enough times for it to become a personal anti-pattern I keep an eye out for.
• People change code and do not change the comments/documentation. The more redundent documentation there is the worse this problem gets.
• Documenting to early. If you're in an environment where the code is changing rapidly, methods and classes are being refactored and moved around on a daily basis, etc. then time spent documenting and commenting is wasted time.

Personally, I tend to go for development environment with common code ownership and require unit tests for everything. I find this removes most of the need for comments and heavy API documentation during development.

If the team discovers a need for documentation during development then we do it. If the team is not in-house then we will also have appropriate levels of design & implementation documentation as a deliverable (and we'll do it properly too :-)

This has worked well for me with smallish projects (about a dozen coders max).

---

---

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.