2010/9/7 Tim Starling <tstarling(a)wikimedia.org>rg>:
Note that the advantage of minification is somewhat
inflated due to
the nature of the source. There seems to be a "because we can" element
to it: because the developers are so impressed by the concept of
minification, they write excessively verbose and excessively many
comments. For example:
[...]
I think it's ironic that this style arises in JavaScript, given that
it's a high-level language and relatively easy to understand, and that
you could make a technical case in favour of terseness. C has an
equally effective minification technique known as compilation, and its
practitioners tend to be terse to a fault. For instance, many Linux
kernel modules have no comments at all, except for the license header.
I don't think terseness is a good thing necessarily. Some comments are
unnecessarily verbose, yes (your first example, for instance), but I
think Javadoc-style comments for non-trivial functions are essential,
and class/file/interface comments describing an interface other code
can interact with (your second example) are also very useful. Both,
especially the former, are used throughout MediaWiki's PHP code, and
the JS code is no exception. I also don't think that the verbosity you
mentioned is caused by a "because we can" mentality, but rather by the
authors themselves: 2 of the 3 main authors of UsabilityInitiative
have a habit of writing verbose comments, both in JS and in PHP. (I
remember you criticizing PHP code written by Trevor in July 2009 for
containing comments verbose to the point of almost insulting the
reader's intelligence.) However, clear and adequately complete
documentation should not be confused for excessive verbosity. I agree
that your second example is a long doc comment, but I don't think it's
excessive for what it's supposed to be documenting (the interface to
.suggestions(), which takes 12 arguments of various types and with
various semantics, allowed values and default values).
Roan Kattouw (Catrope)