This document is intended as a guide for CMP 12A/L students and readers. It is modified from earlier guidelines for this class.
Working Together:
What is Pair programming:
Log file:
Each student must fill out an electronic log indicating the time you spent to complete the program. For students working in pairs, each student must fill out a separate time log indicating their perceived contributions. Failure to turn in a log will result in a 10 point penalty.
Grading scale for programming assignments:
(Note: this is a general scale, which may vary from program to program.
Please see rubrics for the particular lab or prog assignment.)
110 (Extra features or particularly elegant):
Possibilities include support for user input of multiple data sets,
and testing for proper input (e.g. program doesn't crash when non-numeric
data is encountered on a numeric read, etc.)
Generally not applicable to program 1.
81-100 (Satisfies all requirments - a job well done):
1 Syntactically correct - it compiles cleanly
2 Proper comments including name, date, assignment number and
program description in opening comment, and at least one useful
inline comment.
3 Proper and consistent indenting.
4 Descriptive variable names (e.g. numQuarters not q or x for the
number of quarters entered by the user).
5 Correct output.
6 Descriptive, well formatted output.
7 Not inefficient programs.
8 Elegant coding.
61-80 (Meets general requirements with a few minor problems):
Lacking one or two of 2-4, 6-8
41-60 (Serious problems):
Lacking more than two of 2-4, 6, or lacking 5.
21-40 (Extremely serious problems but demonstrates some effort and understanding):
Lacking 1.
0-20 (Shows little effort and does not represent passing work):
Clean compilation
Code structure and Readability
Naming: Use descriptive names for variables, methods, etc., for example ReverseString, NumOfStudents. Short or single-letter names are acceptable if they are used in a small part of the code and their meanings are clear; for example, i and j (lower case) are conventionally used for loop counters and array indices. It is suggested that you capitalize names according to the formatting guidelines outlined below. However, you may use another scheme if it is well thought out. Be consistent.
Avoid use of magic numbers in your program.
Documentation: A program should be properly formatted and commented. It should begin with a header comment called the preamble. The preamble should contain the following information:
The preamble should be enclosed in a box to make it stand out from the rest of the program. For example:
/*********************************************************************/
/* Program: PreserveFreeSpeech */
/* Authors: Judge Judy (judgejudy@cats) */
/* Judge Hatchett (judgehatchett@cats) */
/* Judge Joe Brown (judgejoebrown@cats) */
/* Judge Mathis (judgemathis@cats) */
/* */
/* CMP 12A/L, Winter 2015 */
/* Programming Assignment #1 */
/* January 16, 2015 */
/* */
/* This programs figures out whether telemarketers, politicians and */
/* non profit organizations have the "free speech" right to enter */
/* anyone's home through the phone line. */
/* */
/* Input: */
/* Lawyers arguments, constitutional laws, polls, etc. */
/* */
/* Output: */
/* Development of technology to block junk calls, or a national */
/* do-not-spam list. */
/* */
/* Bugs and limitations: */
/* Success rate is 99.99% unless someone really blew it. */
/*********************************************************************/
A similar, although simpler, comment block should precede each method. It should give the name of the method and its purpose, and describe all information passed into and out of the method, and the meaning of each item. Note that the comment box also makes it easier to see the scope of each method. See example below.
/*********************************************************************/
/* DrawRectangle( Point corner1, Point corner2 ) */
/* */
/* Draws a rectangle in the current color using the 2 points as */
/* diagonally opposite points. */
/* */
/* Input: 2 diagonally opposite points. */
/* Output: Really nice looking rectangle. */
/*********************************************************************/
Use in-line comments to describe the purpose and operation of sections of code. These should be at a high semantic level, e.g.
/* Find the largest element in the array. */
Generally, you will include one comment in the program body for each major algorithm step. A comment within the program body should describe what the step does rather than simply restate the step in English. In addition, on each line whose purpose is not intuitively obvious, use a short comment to tell someone reading the program what is going on. For example:
/* Find the minimum of FirstNum and SecondNum */
min = (FirstNum + SecondNum - abs(FirstNum - SecondNum))/2;
rather than
/*
* Add FirstNum to SecondNum, subtract the absolute value
* of their difference and divide that value by 2.
*/
Use comments to state assertions that you expect to be true at a
particular point in the program. This makes
the program easier to understand and debug. For example, the following
assertion might be placed right after a loop.
/* Here Max contains the largest element of the array */
Order
The text of a program should be arranged in a way that suggests its structure, in order to make it as clear and readable as possible. Make sure all lines are 80 characters or less. That is, use carriage returns! Sometimes they wrap around on the terminal and look right, but get cut off when the program is printed or turned in.
Capitalization
Classes typically start with a capital letter,
while methods and variables typically start with a lower case letters.
If the class, method, or variable names consist of
two or more words, capitalize the first letter of each word.
Examples: class ForgetCampaignPromises;
method buyVotes;
variable howMuch.
We recommend that you follow this convention
in your programs to improve its readability.
Indentation
Vertically align constructs to show where they pair up. For example: scoping {...}, if ... else, switch, while. Use spaces to indent, not tabs, because tabs are handled differently by different output devices. A program indented with tabs that looks fine on a terminal may come out very strange when printed. Single-line and block comments should be indented to match the thing they refer to.
Blank lines
Blank lines should appear before and after comment blocks, and may be used to break a program into logical sections. Avoid using too many blank lines, because they waste screen space and make the code look chopped up. Use more than one only for very significant breaks in large programs.
Lists
Long lists of declarations, method parameters, and enumerated type names may be arranged vertically, indented one step from the line that begins the list. Do this if the list items would be hard to read if jumbled together, or if explanatory comments follow each item. For example:
int PlayVideoClip(
int CompressionMethod, // mpeg, quicktime,..
int PlaySpeed, // slow-mo, fast-fo
int Volume, // 0..9
movie_t VideoClip)
Last modified Sunday, 28-Dec-2014 08:13:52 PST.