Hi! > 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 ;-). Eric ------------------------------------------------------------------------- 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. http://sourceforge.net/powerbar/db2/ _______________________________________________ Freedos-user mailing list Freedosfirstname.lastname@example.org https://lists.sourceforge.net/lists/listinfo/freedos-user