begin quoting Bob La Quey as of Wed, Jun 27, 2007 at 04:21:43PM -0700: [snip] > I agree with Chris here. It is not arrogance to expect someone > reading a language to understand the language. After all would > you criticize a poem written in Spanish because it was not cluttered > with English documentation.
If it was in a book titled "Annotated Spanish Poems For English Readers", sure. Why not? Compilers and interpreters don't require or especially desire comments. Posting code for others to admire, on the other hand, indicates that the code is aimed at something other than a compiler or interpreter. > I find that documentation often adds "clutter" to the visual aspects > of a program. I despise that kind of documentation, which IMNSHO > actually makes a program harder to understand. Yes, there's the "We're required to write documentation, therefore, we will write documentation." meme that results in *terrible* documentation. This is not the sort of documentation that I'm talking about. I agree that bad documentation "clutters" the code. I have been guilty of such documentation, mostly when I have been given a rule that says "all functions shall have documentation". On the other hand, consistency is sometimes a good thing. > It seems that you are demanding that "I should be able to glance at > code written in a language I do not know and immediately understand it." Not quite. What are the assumptions? Limitations? Expected usage? Pitfalls? What does a comment *look* like? (The Java example had a smattering of comments, at least, even if they were mostly not useful.) > Your attitude is the one that I find arrogant. Learn the language first > then render an opinion on a style. In other words, "drink the koolaid". Bah. ... And yet, there's a point there. I expressed myself poorly. Apologies to all. -- When you release code for public consumption, it ought to be documented. Stewart Stremler -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
