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], 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
