2010/9/7 Tim Starling <tstarl...@wikimedia.org>: > 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) _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
