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
