I was a programmer for 31 years; I wrote, read, debugged and documented a lot of code during my career. Peter Coffees insights into this subject in his Feb. 6 column, “Making Code Perfectly Clear,” are lucid as well as entertaining (Epicenters).
The comments in code can be, and often are, misleading, incomplete or missing, making for very poor documentation. Ive found that it is very common for programmers to not be very good writers of understandable prose.
One of the best programmers I ever worked with was great at writing elegant and accurate code, but if we didnt know what his code was supposed to do, it was useless to read his comments and documentation in our attempt to understand it.
Gary Fancher