> It is a discussion about code commenting covering why it should be
> done, how it should be done, and why it isn't done.
> It is always better to go from design to code instead of vice versa
> or just plain code.

> www.artima.com/forums/flat.jsp?forum=106&thread=4183&start=0&msRange=15

Very nice discussion, yes :-). Some examples:

"code is the documentation"

"Grep the Source, Luke!"

"The act of *explicitly* writing out your thoughts forces a mental state
 that is quite different from when you just mull things over and then go
 code. Comments are as valuable to the person writing them as the people
 reading them."

"A colleague of mine, when "questioned" about a lack of comments in his
code replied that writing comments took too long because he always changed
his mind halfway through writing a method as to what it would do. He
didn't like to have to go back and re-write his comment! ...
I pointed out to him that if he took a little time to think about what the
purpose of the method was before he wrote it he would be less likely to
make significant changes to it's purpose. A good aid in doing this? Write
the method comment first of course :-)"

"A comment which describes the implementation rather than purpose and
use is a waste of time!"

"I have had the experience of changing my design as a result of writing
comments and I thought that was a good thing. I would prefer to have my
code influenced by the thought that takes place when explaining and
rationalizing it."

"Why isn't good documentation the norm? Programmers aren't
rewarded for it."

I agree on the latter - I usually TAKE time to have reasonable
comments in my code because it is open source (so others can
reuse it or help improving it) or because I simply insist on
having maintainable code. It hardly ever happens that you GET
significant time on your schedule for maintainability or deep
maintenance work like audits. Customers only PAY for features
and few IT people think about the point that code does and
will change, so you better make it maintainable from the start.
Good luck with convincing your colleagues ;-).


This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
Freedos-user mailing list

Reply via email to