On May 4, 2009, at 5:19 AM, David Woolley (E.L) wrote: > hen I started in the software industry, one of > the first things one was told was that one should document code as > though one expected to be run over by a bus, the next day.
As a fellow software professional, I agree with you in theory. However, things in the real world don't always work according to theory. With a small shop, especially in a start-up, doing things in this fashion might make the difference between shipping the product and making money, or delaying shipment and going broke. You can probably count the number of programmers who have written K2 firmware on the fingers of one hand. With such a small community, it may be simpler to communicate using "tribal knowledge" than extensive documentation. The biggest problem I find professionally with code documentation is that external documentation often goes completely out of date by the time it is written and is rarely updated. Internal code documentation fares little better -- but it is at least close to the actual code. The best advice I've found is to follow the 40+ year-old findings of Gerald M. Wienberg in "The Psychology of Computer Programming" -- the only hope for creating readable code is to have programmers regularly read each other's code through a process of code review. Bill Coleman, AA4LR, PP-ASEL Mail: aa...@arrl.net Web: http://boringhamradiopart.blogspot.com Quote: "Not within a thousand years will man ever fly!" -- Wilbur Wright, 1901 ______________________________________________________________ Elecraft mailing list Home: http://mailman.qth.net/mailman/listinfo/elecraft Help: http://mailman.qth.net/mmfaq.htm Post: mailto:Elecraft@mailman.qth.net This list hosted by: http://www.qsl.net Please help support this email list: http://www.qsl.net/donate.html