[theme-reviewers] Heavily Commented Javascript Files.

[Chip Bennett]

Heh, fire away!

Oenology is intentionally over-commented (if anything), given that, at the
end of the day, its underlying purpose is to be a teaching tool. That said,
while I would probably pare down on the inline documentation somewhat if I
were optimizing for end-use, I wouldn't cut out all that much. I've really
grown to appreciate the usefulness of phpDoc.

Chip

On Tue, Jul 5, 2011 at 9:42 AM, Edward Caissie <edward.caissie at gmail.com>wrote:

> @Mike -
>
> Not to point any fingers or anything (@Chip ... duck); have you had a look
> at the Oenology Theme?
>
> Now there is documentation, perhaps not in the same vein as what you have
> in mind but something to consider when looking at a code to comment ratio.
>
>
> Cais.
>
> PS: I'm not knocking the documentation of the existing theme or the
> proposed one, I've always believed the better the documentation the better
> the code. EAC.
>
>
> On Tue, Jul 5, 2011 at 9:46 AM, Michael Fields <michael at mfields.org>wrote:
>
>> Possibly, but that's a matter of opinion. Personally, I find that
>> undocumented code is harder to maintain in the long run. I definitely do not
>> agree with that article though as the "docblock" style example is a bit
>> over-the-top while the function most-likely does not need to be documented.
>> Everything in-between is not covered. For me, documentation serves as a
>> record of intention. If the words do not match the code, it is easier for me
>> or someone else to debug. I love it! You can't make me stop :)
>>
>> On Jul 5, 2011, at 6:32 AM, scribu wrote:
>>
>> Michael, if 50% of the file is made up of comments, then you might be
>> doing something wrong. See:
>>
>> http://www.codinghorror.com/blog/2008/07/coding-without-comments.html
>>
>> --
>> http://scribu.net
>> _______________________________________________
>> theme-reviewers mailing list
>> theme-reviewers at lists.wordpress.org
>> http://lists.wordpress.org/mailman/listinfo/theme-reviewers
>>
>>
>>
>> _______________________________________________
>> theme-reviewers mailing list
>> theme-reviewers at lists.wordpress.org
>> http://lists.wordpress.org/mailman/listinfo/theme-reviewers
>>
>>
>
> _______________________________________________
> theme-reviewers mailing list
> theme-reviewers at lists.wordpress.org
> http://lists.wordpress.org/mailman/listinfo/theme-reviewers
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.wordpress.org/pipermail/theme-reviewers/attachments/20110705/94bcdb32/attachment.htm>