Re: Code Comments
Re: Code Comments
- Subject: Re: Code Comments
- From: Dov Rosenberg <email@hidden>
- Date: Wed, 16 Aug 2006 07:53:09 -0400
- Thread-topic: Code Comments
Title: Re: Code Comments
We have a lot of code that is commented out that was left in with an explanation of why it was commented out. Instead of just deleting code that might cause us issues in the next release and then we struggle to figure what change actually caused the problem it is easier to look at the code in its original context. Eventually we try to go back and delete the commented out stuff after it has been running good for awhile.
People are going to ask – why don’t you use the diff functionality of the source control system (we use Subversion)? We make lots of updates to all sections of our code and make frequent releases (about every 3 months). Trying to track a specific change thru a raft of revisions over a 3 month period of time can be painfully slow. Leaving the commented out code in place for a release or two may add some size to the code but the time saved tracking down problems is much more important to us. Usually a defect related to a recent change is easily fixed by looking at the changes made.
Dov Rosenberg
On 8/15/06 11:16 PM, "Ian Joyner" <email@hidden> wrote:
On 16/08/2006, at 12:24 PM, Dov Rosenberg wrote:
Like usual the threads have been hijacked from their original purpose. I just thought I would throw my 2 cents in about code comments:
We have a team of 3 developers working on our application. Instead of having 1 person specialize in one area of our application, each programmer works on a wide variety of tasks usually working on an area where someone else has worked before. It is our form of code review and works pretty well.
I have told the guys that I don’t need to see comments that explain what I can read. I want comments that explain WHY we are doing things the way we did.
That's very well put, I think I'll come and work for you.
If you look in our code you will see little explanations of the conversations that we had about a particular feature usually along with a date and initials. That way when the next guy looks at the code they have a bit more context as to why something was done versus what was done. This becomes helpful is explaining how a feature works when someone goes to write documentation sometime in the distant future or when trying to debug some cryptic logic.
A downside of that, is that everything can get preserved and not rationalized. So you have a lot of non-maintained comments. Don't know if that is what you mean.
Design by contract is great for code compile and runtime checking but still doesn’t explain the mental state (or lack of) the dude working on the code that day.
Design by contract is more than just code compile and runtime checking, it is actually an essential part of the documentation as well and it's great to kill a single bird with one stone. That is the point of DBC that while producing self-documented code, a programmer is actually producing something that is useful as well, so has motivation to do it and do it properly, which helps understand the API since to a user it expresses constraints such as a_vowel: where a_vowel = 'a', 'e', 'i', 'o', 'u'. As a caller, that's what I want to know - I don't think I want to know the mental state of anyone working on the code (at least long term).
Ian
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden
--
Dov Rosenberg
Inquira Inc
370 Centerpointe Circle, ste 1178
Altamonte Springs, FL 32701
(407) 339-1177 x 102
(407) 339-6704 (fax)
email@hidden
AOL IM: dovrosenberg
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Webobjects-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden