UNIVERSITY OF CALIFORNIADepartment of Electrical Engineeringand Computer SciencesComputer Science DivisionCS61B P. N. HilfingerSpring 1998General Guidelines for Programming ProjectsThe programming projects constitute the most important, time-consuming, strenuous, frustrating,and fun part of any programming course. Unfortunately, they are also the most time-consuming anddifficult coursework to grade. The criteria for a program being good are not easily defined.Good programs must, of course, work. Even such an obvious statement is not as simple as itseems. For example, a program that works most of the time can be extremely useful, even thoughthere are some inputs for which it fails. In such cases, it is naturally desirable that the programdetect its failure and avoid disastrous actions, and that the documentation of the program indicate itslimitations. A program may work correctly for all legal inputs, but fail on illegal inputs. True, that’snot the program’s fault, buta program designed under the assumption that input will be perfect reflectsrather badly on its implementor’s grasp of reality.Furthermore, our program descriptions (as in real life) tend to be incomplete or ambiguous. Thereare some details of a program that are either unimportant to pin down, or that require some designto get right. For example, the handling of erroneous or pathological input is generally not part of aproject description. It is assumed that the programmer will “do something reasonable.” So it will bein this course; you will be expected to recognize places where you must fill in details of the design,to fill them in some reasonable fashion, and to document your decisions, where appropriate.Beyond mere functional correctness, good programming demands some attention to the processof programming itself and to stylistic qualities of the program produced. Programs tend to last longerthan we originally intend. As a result, others (or even we, years later) must be able to read, understand,and modify them. Readability in programs, as in books, requires clear and logical organization andclear, straightforward expression. Errors in well-organized programs are easy to find, since it tends tobe clear where the error must be.Finally, the current state of the art does not allow us to forgo testing our programs. While testing,in Dijkstra’s oft-quoted phrase, “can show the presence of bugs, but not their absence,” it is the usualmethod of increasing our confidence that our programs, though probably not perfect, are fit for theirintended purposes. Too often in programming courses, we spend much too little time on this subject.I venture to guess that most of you have been content to run a few examples through your programs—say, the examples given in the problem description—and then turn them in as quickly as possible,6364P. N. Hilfingerlest continued testing uncover another ten hours’ work. In real life, something more systematic andthorough is called for.Programming style often becomes a “religious” issue amongst practitioners. These particularreligious beliefs, however, are not among those protected by the Constitution, and I will accordinglyfeel free to lay down some law in the rest of this document.1 DesignIn CS 61B, you will not be called upon to do real program specification from the bottom up, but therewill always be minor gaps and ambiguities in the project descriptions, and you will be expected toresolve them appropriately. Where needed, you will also be expected to document what you’ve done(see section 4).It is difficult to say anything general about what “appropriate resolution” is, but a few pointsare clear. It is appropriate that programs detect erroneous input; make some attempt at isolatingand reporting the problem; and terminate or recover gracefully (i.e., by some means that, unlike asegmentation fault or a Java stack dump, gives the impression of being planned). It is appropriate thatprogram inputs and outputs be non-cryptic. It is appropriate that programs fail gracefully when theyrun into implementation limits. For example, an appropriateresponse to running out of memory mightbe to print a message to that effect, remove temporary files, and terminate cleanly. If your programfails to check for this situation, you will probably end up with an abrupt and enigmatic exception or(in C and C++) segmentation fault.2 Modules, Headers, CommentsI am not a big fan of internal comments, such as this sort of thing.if (qr > z + 1) { // Check for end-of-bufferputs(buf); // ... and start new line if needed.qr = 0;}I would much rather see subprograms (procedures or functions) chosen and named to make the sourcecode self-documenting:if (endOfBuffer())beginNewLine();Each subprogram, in turn, can have a single comment at the beginning (either just before the subpro-gram, or just before the opening ‘ ’ of the body) that explains what it does. Indeed, a sufficientlysmall procedure with a self-documenting name may need no comment (for example, endOfBuffermay well not need a comment, but beginNewLine probably does). The test of ideal commentingon subprograms is that a programmer browsing through a particular piece of code can tell what itdoes by consulting only the comments and headers of the subprograms it calls and the comments anddeclarations of the variables it references.General Guidelines for Programming Projects65These comments on subprograms should not generally mention just how a subprogram does whatit does. As the previous discussion suggests, the body of the subprogram should suffice for that.When the subprogram gets too complicated for this to be feasible, it’s probably time to break it up.Occasionally, the algorithm employed will be sufficiently subtle that you’ll want to say somethingabout it. In this case, use a separate comment(possibly at the beginning of the body of the subprogram)to describe the algorithm.All this assumes that you choose reasonable things for subprograms to do. A beginning program-mer tends to bundle together the strangest sorts of activities into a single subprogram. If you had towrite a comment describing one of these, it might read like this./** Outputs characters pos[k] through pos[k+1] of S; increments* count[n] by pos[k+1]-pos[k]; reads the next line into* S, starting at pos[m], unless stopRead is true; and sets* stopRead to false. */int doIt(int n, char[] S)This can’t be described by a simple crisp phrase, because it doesn’t correspond
View Full Document
Unlocking...