[theme-reviewers] Heavily Commented Javascript Files.

[Darren Slatten]

>
> *Michael, if 50% of the file is made up of comments, then you might be
> doing something wrong.*


Not exactly.

While it's certainly true that *good code requires less commenting*, there
are 2 important differences between Mike's code and the code in the Coding
Horror (CH) article<http://www.codinghorror.com/blog/2008/07/coding-without-comments.html>
:

*Audience* - CH assumes the code is being documented by developers and
*for*developers. In other words, it addresses the use case where
software
developers need to make their code understandable to other software
developers. In Mike's (and Chip's) case, the audience is assumed to have
only *very* *basic* coding skills, thus the documentation needs to be more
comprehensive.

*Language* - CH assumes the code will be compiled, and therefore the
programmer has more flexibility in terms of which coding patterns to use. In
other words, the program's logic can get from point A to point B via the
"scenic route," because most of those inefficiencies will be ironed out by
the compiler and won't affect performance. In Mike's case, however, the code
is interpreted at runtime (ie, it is *not* compiled), so he needs to write
code that gets from A to B as soon as possible. The main idea in the CH
article is to refactor your code to be more readable *without comments*, but
with JavaScript, the code's natural readability usually drops as
performance/efficiency increases. Thus, higher performing JavaScript
applications may require more comments to explain what's happening in the
code.

Also note that these differences pertain to performance in terms of code
execution and ignores the fact that the JavaScript code will presumably need
to be sent to the users' web browsers. Therefore, an increase in JavaScript
comments will also decrease page load performance. This decrease, however,
is determined by how much extra text is being sent--not by the ratio of
comments to code. In other words, adding a comment to a 1-line script will
have the same performance impact as if you added that comment to a
1,000-line script.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.wordpress.org/pipermail/theme-reviewers/attachments/20110705/c0e3b6af/attachment-0001.htm>