From: Lothar Scholz Date: 2004-09-01T11:57:27+09:00 Subject: Re: Typos (Was: performance comparison) Hello Charles, >> So, where do you think this "code + documentation = Good", comes from? >> Does it help to reduce maintenance costs? My experience says yes. >> Empirical evidence seems to support that conclusion as well. Is it >> taught in universities etc.? No. Does it make "real world" sense? >> Yep. In my university i got a lot of courses where this was taught with many different modells, most of them UML and Z (a specification language). >> Is it used within my organisation? No. Should it be? Yes. How come? >> 'Cause coders, code, they don't write documentation. 'Cause, on the >> whole, those writing the code don't have to maintain it. I agree. But i think very often they also have to maintain it. CM> Seems like Lothar is doing most of his coding in Eiffel which uses CM> Design by Contract. IMHO contracts generally provide good CM> documentation and as a bonus the coder writes the contract. Also CM> contracts are check at runtime - so they stay current, which means the CM> docs stay current (if they are generated from the contracts/code). CM> -Charlie Write the only technique that guarantees to stay in sync with the code. And one word to the API /Doxygen documentation: Yes this is used intensively in some companies but it still becomes very hard to maintain if people use it not for the static but the dynamic modell. I mean message flow, algorithms etc. This changes much more then most API functions. I found that it is almost impossible to keep the documentation for this up to date. I'm also only writting UML class diagrams and never Sequence/Collaboration Diagrams etc. So instead of writing embedded documentation people should write better code: using long identifier names, avoid 10 times nested loops, use small methods and no tricks to save a few keystrokes. -- Best regards, emailto: scholz at scriptolutions dot com Lothar Scholz http://www.ruby-ide.com CTO Scriptolutions Ruby, PHP, Python IDE 's