Re: Comments in code

["Michael Wayne Goodman" <goodman m w gmail com>]

Stephane:
The reasons you listed surely have some heads nodding in agreement,
but I must object that "the code is easier to read than comments" is
probably only true for those who wrote the code or are already
acquainted with it.  I work on a research project in C# at school, and
we have people always coming in and going out (graduation, etc.).
When the turnover rate of coders is so high, there needs to be some
guidance in order to get them producing code sooner.  With OSS, I
imagine there is a somewhat similar rate of people hopping aboard, and
thus a similar need for documentation.

"The code never lies," indeed, but it sure can be deceptive sometimes.
I believe there is even a contest for the 'art' of code obfuscation.
I don't believe people are purposefully obfuscating f-spot's code, but
I'm just trying to point out that even if the machine easily
understands the code, it does not imply humans can easily understand
it.

I agree that it may be difficult to "keep code and comments in sync",
but I've been conditioned to believe (due to all those college
professors needing to correct students' programs, no doubt) that
commenting code is as important as the code itself.  So just as you
would expect someone to submit code that follows the proper style and
formatting rules (eg. indentation, CamelCase or whatever, etc), you
would expect them to provide the appropriate comments.

And just because the XP methodology dictates that code should be easy
to understand, easy-to-read code is not mutually exclusive with
comments.

Anyway, I'm not trying to force an ideology on f-spot, but just trying
to address why comments needn't be mandatory, but shouldn't be avoided
either.

I don't know if Mono supports it, but MS's C# compiler allows for
xml-structured comments for classes and functions, for example:

///<summary>
/// Does x for y iterations
///</summary>
///<param name="y">The number of times to do x</param>
public void DoX (int y) {...}

If we used that, then (supposedly) we could easily generate code documentation.

Thanks

-mwg