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 8/28/03 9:45 AM, Ricky Sharp didst favor us with:

> I wasn't going to add to this thread initially, but here's my take on this
> subject:
>
> I personally write code comments and comment blocks for most of my code. The
> typical exceptions are for trivial inlined functions (e.g. getters and
> setters).
>
> To me, there is _no_ excuse for excluding comments where needed.

It's the "where needed" part that people disagree about, and how much you
can reduce that need with certain coding practices.

> After all,
> adding comments...
>
> (a) makes things easier to read and understand. Also, there are many
> situations where comments not only describe what the code is doing, but what
> users of the code need to do beforehand. Knowing all the pre-conditions are
> not always obvious from reading the code in a function/method.

Actually, in really robust code, it should be obvious most of the time
because you're validating parameters which are passed in, and if the
function requires some other condition to be fulfilled, it should validate
that as well. That's not to say that there isn't *any* value in explicitly
stating things such as the famous "can be NULL."
>
> (b) it disciplines you. I also think it helps write more solid code.

True. I don't write a lot of comments, but if I'm having trouble getting my
head around what I want to do, some comments in the form of pseudocode can
be a big help.
>
Larry
_______________________________________________
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: Ricky Sharp <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.