rb@ccivax.UUCP (rex ballard) (03/08/86)
In article <1087@burl.UUCP> rcj@burl.UUCP (Curtis Jackson) writes: >In article <11569@watnot.UUCP> jjboritz@watnot.UUCP (Jim Boritz) writes: >>Very few CS courses provide marks for things like style. Sure you will >>lose marks if your programs are not clear, but not for bad sytle. >I had a prof who had two guidelines, both of which I thought were very >sound: > >a) Assembler programs *had* to have at least one line/phrase of comment >per line of code. The comment had better not say, "Load r2 with r1" >or you were history -- they had to be functional. >b) Other programs were graded with one rule-of-thumb: if he had to ask > you how a piece of code worked or why it was there, ... It was bad too, the comments and documentation for a piece of "tricky code" should be included right there in source. >ugly, non-functional, or downright wrong -- "I don't know what the following >2 lines of code do, but the program won't work without them." I have seen code like this, but usually only when the original work was not properly documented in the first place. One of our project leaders insisted on a complete "man page" for every callable routine, to be included in the source code. This had to be extractable by using sed scripts, and was printed at each release. Another useful test was to remove the code, and leave the comments. If you couldn't tell what was going on, there wasn't enough documentation. A third test was to remove all comments from C routines. If variable names were too cryptic to know what was going on without the comments, the code was too cryptic. Of course these were things that I learned in the workplace, but many "old hands" resisted these techniques. Computer students (BA,CS,EE) should be taught early on that the rules and standards will change often. What was "hacking" last year may be "state of the art" this year. Take a look at an object oriented design implemented in a procedural language (like C).