kurtl@fai.UUCP (Kurt Luoto) (12/13/89)
In article <473ae701.20b6d@apollo.HP.COM> perry@apollo.HP.COM (Jim Perry) writes: #In article <9157@hoptoad.uucp> tim@hoptoad.UUCP (Tim Maroney) writes: #>In article <??> dopey@sun.UUCP (Can't ya tell by the name) writes: #>>Regarding (c), well documented to me doesn't necessarily mean lots of comments. #> #>Absolutely. Clear code shouldn't *need* a lot of comments; #> [...] #>In summary: Clear code is far more important than extensive comments. # #Clear code and clear comments are both important. [...] # [...] #>Again, I agree. External documentation is very useful; far more so than #>most code comments. # #Again, you're throwing out the baby with the bathwater. # [...] #As Fred Brooks says in The Mythical Man-Month: # [...] # "The solution, I think, is to merge the files, to incorporate the # documentation into the source program. [...]" # # [...] It is true that what Knuth calls a literate programmer #must have both the skill of coding, and that of documenting. All #programmers are in effect technical writers, documenting their work for #other programmers who will see it/work on it. Not all current programmers #excel at both of these skills, but it is a goal to aspire to. # [...] Noble goals, I agree ... #For instance, let's say I've been asked to change the memory allocation #implementation of a moderately large program I've never seen before. # [...] #In that module's primary .c file is a description of the general memory model, #a breakdown of the operations on that memory (functions in the module), and #perhaps a summary of what the cost and benefit of that model are compared #to likely alternatives. At each subsidiary function the particular #algorithms used are described, potential pitfalls, potential interaction #with other functions. Within a function the variables are described, and #the high points of the algorithm, such as potential trouble sites for #concurrency, etc. I too have experienced the dangers of external documentation that F. Brooks describes (it tends to become out-of-date with the code). But at the same time, I have learned that these extensive comments in the source code, which would otherwise best be placed in external docuemntation, also suffer the same problem. Programmers don't bother to update them unless allowed the time (and forced) to do it by the development process (read schedule, management, procedures, etc). (Hence the advice to beleive the code before you beleive the comments.) From this fact, combined with other concerns, such as readability, I have become convinced that such extensive comments belong in separate external documentation rather than embedded in C-style comments. The purpose of the C comments is to document the *implementation*, not to give the extensive reasoning behind the design decisions. Again, its the application of the principle of "separation of concerns" that is used so well in engineering and science. I could perhaps see the benefits of combined documentation (source code embedded in the documentation, not vice versa) but only when made more amenable by tools along the lines of Knuth's WEB/WEAVE system. #There's not much time overhead in generating this documentation, assuming a #basic competence at technical writing to one's own level. At design time #most of this information is probably either already written down or on the #forefront of the programmer's brain (I often design code by writing the #documentation). [...] The statement may be true, but from my experience, that's one helluva big assumption. I have found very few programmers who have decent technical writing skills. I like to think that I do a good job of it, but I find that even when I do, it takes a lot of time (= overhead). Even if I have all the info available at the time of writing, it is not easy to figure out how to best present it for easy digestion by future readers. The best organization of such information does not always follow the organization of the source code. #Jim Perry perry@apollo.com HP/Apollo, Chelmsford MA -- ---------------- Kurt W. Luoto kurtl@fai.com or ...!sun!fai!kurtl