I'd write it:
/* This is an implementation of the Pythagorean Theorem for the distance
between two points. More info at
http://mathworld.wolfram.com/PythagoreanTheorem.html */
public double calculateDistance(double changeInX, double changeInY)
{
double xSquared = changeInX * changeInX;
double ySquared = changeInY * changeInY;
double sumOfChangesSquared = xSquared + ySquared;
double distance = Math.sqrt(sumOfChangesSquared);
return distance;
}
Gives info for the uneducated, and doesn't repeat itself. Incidentally, the
MathWorld article on the Pythagorean Theorum is pretty cool.
-B
On Thu, Feb 21, 2008 at 1:09 PM, Landon Blake <[EMAIL PROTECTED]> wrote:
> I've got a quick question for the guys developing open source GIS
> programs.
>
>
>
> 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?
>
>
>
> For example, most experienced Java programmers would understand the
> following code:
>
>
>
> public double calculateDistance(double changeInX, double changeInY)
>
> {
>
> double xSquared = changeInX * changeInX;
>
> double ySquared = changeInY * changeInY;
>
> double sumOfChangesSquared = xSquared + ySquared;
>
>
>
> double distance = Math.sqrt(sumOfChangesSquared);
>
> return distance;
>
> }
>
>
>
> However, I think one important difference between FOSS GIS programs and
> proprietary GIS programs is the potential for non-professional programmers
> to be reading the source code. This might be users looking to fix a bug or
> add a little functionality improvement. In this case I wonder if it makes
> sense to be generous with your source code comments. (I realize this would
> be a violation of the DRY principle [
> http://en.wikipedia.org/wiki/Don't_repeat_yourself<http://en.wikipedia.org/wiki/Don%27t_repeat_yourself>],
> but perhaps it is justified in these situations.)
>
>
>
> This would help non-professional programmers working on your source code.
> For some projects I would wager helping users move from a role of
> consumption to a role of consumption and contribution would be vital for
> long-term survival. I think OpenJUMP would be one example of this.
>
>
>
> 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;
>
>
>
> /* Calculate and store the value of the change in Y squared in a
> local variable. */
>
> double ySquared = changeInY * changeInY;
>
>
>
> /* Calculate and store the sum of the change in Y squared and the
> change in X squared
>
> * In a local variable.
>
> */
>
> double sumOfChangesSquared = xSquared + ySquared;
>
>
>
> /*
>
> * Calculate the distance using the values calculated previously in
> this method using the
>
> * the square root method of the Math class.
>
> */
>
> double distance = Math.sqrt(sumOfChangesSquared);
>
>
>
> /* Return the results of our calculation.
>
> return distance;
>
> }
>
>
>
> Thanks for your comments.
>
>
>
> Landon
>
>
>
>
> *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
>
_______________________________________________
Geowanking mailing list
[email protected]
http://lists.burri.to/mailman/listinfo/geowanking
