Apple

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).

References:
	>Code Comments (From: Dov Rosenberg <email@hidden>)