Re: Comments in code

[Stephane Delcroix <stephane delcroix org>]

Hi all,

I never said we shouldn't write comments, I just explained why I write
so few of them in the code I commit and that I prefer no comments at all
that bad or incomplete ones.

Obviously, if Larry wants to change the code policy, I'll do my best to
follow it.

regards,

s

On Fri, 2006-12-29 at 14:03 -0800, Michael Wayne Goodman wrote:
> 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
> _______________________________________________
> F-spot-list mailing list
> F-spot-list gnome org
> http://mail.gnome.org/mailman/listinfo/f-spot-list
> 
-- 
Stephane Delcroix
stephane delcroix org