On Mon, Dec 25, 2006 at 06:44:25PM +0100, Juliusz Chroboczek wrote: > > But then again, after watching Haskellers at work, I'm starting to > > side with the "comment less, code better (*)" > > Sometimes also known as the ``it was difficult to write, there's no > reason it should be easy to read'' crowd.
Is this flame bait, or what? Then I'd like to join and, eh... share a good rule of thumb. ;-) A comment should explain "why" or "how", not "what". The "whys" are the most important ones. They are short, and usually occur directly on the affected line of code. They explain non-obvious things forced by the design. A good design has few or no whys, but a simple design with a few whys is better than a complicated design with no whys. The "hows" are good, but unfortunately very rare in common code. They are longer pieces of text, although brevity is preferred, explaining larger or smaller parts of the code's design. They can also be dividers or headings emphasizing the layout of the code. This is very handy for someone not familiar with the code, and can save tremendous amounts of time. If the function and data decomposition of the program is good, the how comments will be short. If the code is not describing "what" it's doing by itself, it is better used as a contribution to an obfuscated code competition. Unfortunately it is much more fun to write obfuscated code than code that is and looks simple, although both extremes are equally hard. Hard-to-read code with "what" comments is of course much much better then hard-to-read code without "what" comments, and since it's difficult to write simple code... So I do believe there is a crowd such as Juliusz describes, but I don't think (or hope) it's the same crowd as Eric describes. > Merry Christmas to you ! And a Happy New Year! -- Tommy Pettersson <[EMAIL PROTECTED]> _______________________________________________ darcs-devel mailing list darcs-devel@darcs.net http://lists.osuosl.org/mailman/listinfo/darcs-devel
