Comments are things the even professional programmers arguably don't get
right all the time - some never do!
My personal choice is to comment every subroutine/method with :
* name
* purpose
* parameters in (name, type, purpose)
* results returned (name, type, purpose)
* Expected error codes generated here
Additionally, where the purpose of a piece of code isn't obvious to a
reasonably skilled programmer, that gets commented too. For the most
part comments aren't intended for beginners, they're intended to support
another professional who has to understand what I've written.
However, the best commented code I've been involved with was a nuclear
fusion simulator in Fortran (shows how long ago this was!). The
documentation was a published research paper about 30 pages long that
described the layout of the multiple modules, subroutine hierarchy
resource needs, expected run time and so on. In other words - not code
comments at all (although there were many). The system was intended from
the outset to be modified by other physicists rather than by
programmers.
Overall, my suggestion is not to look for standardisation, but for
clarity - but understand who you're writing comments (and other
documentation) for.
Regards,
Hook
On Thu, 2008-02-21 at 13:09 -0800, Landon Blake 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], 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
