[Geowanking] FOSS GIS Programming Style - Different Standard For Source Code Comments

[Mateusz Loskot]

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?

Landon,

In my opinion, sources of FOSS shall be well documented.
However, well should also mean that excessive comments are avoided.
Here, I'd quote Stephen Dewhurst's book:
http://safari.oreilly.com/0321125185/ch01lev1sec1

> 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.

Yes, but I'm not sure if non-hackers are supposed to dig into 
implementation details, rather they should be interested in function 
comments - a comment block related to function prototype or class 
definition.

// Here is a comment that non-pro may read and should understand
// without problems.
void foo()
{
    // but this one is mainly for programmers
    // so non-hackers should not be surprised they can not
    // understand it.
}

> If this is true, the method above might look like this:
> [...]

Honestly, I'd consider this style of comments as very excessive.

Best regards
-- 
Mateusz Loskot
http://mateusz.loskot.net