djones@megatest.UUCP (Dave Jones) (02/14/89)
From article <20233@agate.BERKELEY.EDU>, by hughes@math.Berkeley.EDU (eric hughes): [...] > >> If you do that, and >>if the code is well structured, documenting an algorithm is usually >>(but not always) unnecessary. Usually it is obvious how the algorithm >>will go about the process of reestablishing a broken invariant. > > I always document an algorithm, not matter how silly. This has > helped me avoid what I term "typo bugs," things I meant to do > but forgot. > Go ahead and write all the comments you want while you are developing the code, to help you avoid those "typo bugs". But my personal preference is that you remove the comments of those "silly" algorithms before you release the software into the great beyond. >> If the algorithm is not tricky, the WHAT >>will make the HOW clear enough. > > Yes, a good statement of the preconditions and postconditions to a > function can eliminate most procedural comments. Now you're talking! > Now I would like some engineering tools with which I could check my > correctness proofs, but since none exist (to my knowledge), I have > found that conscientious commenting is acceptable. > This is off the subject, but it's something I have been thinking about a little, so allow me to ramble on for a bit, (or hit 'q'). Take the following for what it's worth, which may not be too much... Seems to me there's a chicken and egg problem with computer aided correctness proofs. The universe of discourse about computer programs which computer programs may get involved in concerns state and computable values. That's not too profound, when one considers that a computer is basicly a memory with an ALU. But the universe of discourse of the proofs is couched in terms of the problem -- the thing the program is modeling. So one has a choice: write the invariants in terms of the computer model, in which case you have tacitly agreed that the model is correct -- or write the invariants in terms of the problem, and somehow "teach" the computer about those terms, in which case you tacitly agreee on a model. Hmmm... And there's another problem: The assertions often have universal quantifiers and such that can not reasonably be calculated at runtime. One can perhaps program around some of this by programming a basic understanding of mathematical induction into the machine. But when you start to attempt to do proofs about all possible histories of events and such, things seem to get a little sticky. On the other hand. Sometimes I think *I* do correctness proofs. So if one computer (like me) can do it, seems like another (like my sun 3/60) should be able to do it. Or maybe I'm just fooling myself.
ham@hpsmtc1.HP.COM (Bob Hamilton) (02/23/89)
> Your comments should be a parallel rendering into English. If > anything, you should write comments *first*. Proper documentation > naturally complements the code. BRAVO. Yes. Precisely. My brother once told me "When I'm given an assignment, I first write the user documentation. Then I show it to the person in the next cubicle. When we both agree, I show it to other people on the corridor. When we all agree that the user documentation is complete and correct, writing the code to implement it is trivial." This may be an over-simplification, and please don't flame my brother, but it does illustrate the point I'm trying to make. When I reached the point where I was writing new applications, I had been maintaining old ones for some years. I had been called in the middle of the night to come in and fix other people's stuff more times than I can count (I was in MIS operations support). By the time I began writing serious amounts of code, I had formed some conclusions about comments: 1. Know your audience: A. Does this person know {more, same, less} about the language than you do? Comment accordingly. B. Does this person know {more, same, less} about the application and its environment? In my case, probably less, comment accordingly. 2. Comment on the assumption that the reader has just been called in at 2:00 AM, doesn't know the language very well (or s/he wouldn't be junior enough to be dragged out of bed), and is seeing this whole mess for the first time. Try to give enough information that a reasonably intelligent person can figure out what's going on well enough to solve any immediate problem, and come in tomorrow and make the fix pretty. --Bob Hamilton Software Methods Lab Hewlett Packard Company Cupertino, California (408) 447-5113 ham@hpda