Mailing Lists: Apple Mailing Lists
Image of Mac OS face in stamp
 
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [OT] Commenting source code

On Wednesday, August 27, 2003, at 02:09 AM, Jan E. Schotsman wrote:

I can think of one justification: if you just want to quickly revisit the
function you can just read the red type and think "Oh yeah, I remember
now". Kind of leaving in the original first version pseudocode.

But that's the very problem Larry and I are lobbying against! (arguing is too strong of a word ;)

Because comments have historically never really been updated, later when you "quickly revisit" that code and skim the red colored comments. Guess what? More often that you might believe those comments DO NOT reflect the source code. So now you're think you remember something about the function when the reality is that it may be doing something quite different now.

And with modern syntax coloring, isn't it just easier to skim the blue colored functions and whatever-colored types and constants? (You do have all of your carbon symbols entered as a custom keywords right? It's easy to do and very helpful!)


I've worked in team environments for the past decade and I can say without a doubt that it's much easier to read and understand "clean" code with no comments than it is to wade through "messy" (of course, 'messy' is my definition ;) code with lots of comments from half a dozen different people with initials and dates and version numbers and whatnot and have 75% of the comments just be flat out wrong.

One of the first things I do to try and understand a complex piece of new code that I get involved with is to (a) strip virtually all comments (backups are in CVS :) and (b) refactor (though I actually strip comments as I refactor).

In most cases, after maybe a day or two or three of refactoring all but the most complex code, I find that I intimately understand it and all its nuances.

Of course, this is all my opinion and I could be wrong.... ;)

Bryan
_______________________________________________
carbon-development mailing list | email@hidden
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/carbon-development
Do not post admin requests to the list. They will be ignored.
References: 
 >Re: [OT] Commenting source code (From: "Jan E. Schotsman" <email@hidden>)



Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Contact Apple | Terms of Use | Privacy Policy

Copyright © 2007 Apple Inc. All rights reserved.