[wp-hackers] Re: 1.5.2 or on to 1.6?

[David House]

On 5/23/05, Matthew Mullenweg <m at mullenweg.com> wrote:
> Commenting is tricky. Some "well-commented" code I've seen had a bunch
> of lines of repetitive filler that "documented" what you could easily
> see by just looking at the code itself and doubled the size of the
> program. APIs should be documented religiously, but I think spending a
> ton of time on redundant comments for code only a few core hackers will
> ever look at will bloat the codebase and waste everyone's time. I also
> believe that well-written code usually doesn't need comments unless it's
> doing some sort of voodoo or workaround. (See gettext.php.) If you're
> doing something that is so long and complicated that it needs a lengthy
> explanation, it probably is worth breaking it into several simpler pieces.

I agree. The obessive phpDocumentor style comments just adds far too
much bloat to the code. I'll vouch for general comments to point out
where the code is going, along with specific comments that explain
individual lines if, like you said, 'it's doing some sort of voodoo or
workaround.' The general comments are still pretty important in my
mind, though, so don't discount comments in all cases apart from a
select few.

-- 
-David House, dmhouse at gmail.com, http://xmouse.ithium.net