Thanks to Bill and the others for their comments. I realize now that it was a mistake not to include a Javadoc comment in my example. This would be the place to put most of the comments people mentioned. (For example: Indicating that the method used Pythagorean Theorem.) I excluded the Javadoc comment from the example because I was trying to concentrate on the source code comments.
I am beginning to appreciate that you must assume the reader of your source code has a basic "baseline" understanding of the programming language in use. Source code comments aren't going to fix a lack of that knowledge. Still, some of my programming style has been acquired after working with lots of legacy (or existing) source code. It seems I spend more of my time interpreting the code than I do improving it. This is why I try to avoid things that make source code difficult for me to understand when I write my own code. This includes things like abbreviated variable names and including long chained method calls or operations in a parameter list. I'll think on this some more. I'd like to write a little article or blog post that discusses how one can write source code that is easier for new programmers to digest. At the end of the day Bill's comment hit the nail on the head: " Good comments add information. " Thanks again. Landon -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Quantitative Decisions Sent: Thursday, February 21, 2008 2:48 PM To: [email protected] Subject: [Geowanking] FOSS GIS Programming Style - Different Standard For Source Code Comments Landon Blake wrote: >Do you think there should be a different standard or policy for source >code comments in code used in open source programs, in comparison to >that used in proprietary programs? ... >If this is true, the method above might look like this: > >public double calculateDistance(double changeInX, double changeInY) >{ > /* Calculate and store the value of the change in X squared in a >local variable. */ > double xSquared = changeInX * changeInX; ... This kind of comment merely repeats in English what the code already clearly (and verbosely) says, at the risk of contradiction and confusion. IMHO, it's not an improvement. Good comments add information. The kind that is helpful, especially to someone not intimately familiar with the system and its evolution, focuses on why the programmer wrote the code, how it functions within the system, itse intended use, and limitations. In this case, for example, what procedure(s) would call calculateDistance? What ranges of values might they be expected to pass to it? How is the output intended to be interpreted and used? What might cause it to fail? How will it signal a runtime failure? A good implementation, in addition to providing the usual accounting documentation (who wrote it, when, its change history, etc.), therefore might approximate the attempt below (which might not be entirely accurate; it's just an illustration). Seeing comments like this in open source programs would give me much more confidence in the reliability and accuracy of those programs, as well as a much faster learning curve if I intend to modify them. Otherwise, I'm afraid to say, my default assumption is going to be that the programs are likely to be risky to use, flaky in execution, and untrustworthy (not unlike much of the proprietary stuff out there, too, unfortunately ...). Best, Bill Huber Quantitative Decisions /* * PURPOSE * Apply the Pythagorean Theorem to a 2D vector change in coordinates * in order to compute the distance they represent. Intended as a general-purpose, * low-level, moderately efficient and moderately precise method when performing * distance calculations with projected points. * -- For rapid approximate calculation, see calculateDistanceApproximately. * -- For high-precision calculation at some cost in computation time, see * calculateDistancePrecisely. * * INPUT and OUTPUT * Arguments can be positive or negative. They must lie in the range 1.E-152 to * 1.E+152 in size to avoid underflow or overflow. The result is always non-negative * or NaN (when overflow occurs). Underflows are not trapped. * * LIMITATIONS * Precision is lost when the two arguments differ much in size. In particular, * when |changeInX/changeInY| is around 1.0E-8 or 1.0E+8, only * about eight decimal digits of precision are retained. If necessary, use * calculateDistancePrecisely in such cases. */ public double calculateDistance(double changeInX, double changeInY) { /* Note the potential for overflow or underflow in the multiplications. */ return Math.sqrt(changeInX * changeInX + changeInY * changeInY) } _______________________________________________ Geowanking mailing list [email protected] http://lists.burri.to/mailman/listinfo/geowanking Warning: Information provided via electronic media is not guaranteed against defects including translation and transmission errors. If the reader is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this information in error, please notify the sender immediately. _______________________________________________ Geowanking mailing list [email protected] http://lists.burri.to/mailman/listinfo/geowanking
