CPSC 120 Programming Standards

Consider a paper you are writing for a course. It is certainly important that you get the English grammar correct and arrange your ideas in a logical order - without that, your reader will have no idea what you are talking about. It is similar when you write Processing code - if you don't get the syntax right and the steps arranged in the right order, the computer won't be able to correctly display your page or run your sketch.

But think back to that paper for a minute. Your professor probably also specified some formatting requirements - that the paper be double-spaced or use a certain size font or have certain margins, for example. The spacing and font and margins have nothing to do with the correctness of the paper in terms of the ideas you are expressing, but are important for making the paper easier to read. Similarly, there are established programming standards which dictate things like spacing, indentation, and naming styles in your program in order to improve understandability and readability for humans beyond simply having a correctly-executing program.

You should follow the style of the examples in the textbook and in class. Some rules are summarized below for convenience. You will lose points for lack of readability, even if your code is otherwise correct.

Processing

Give variables and functions descriptive names of an appropriate length:

• Avoid excessively long and excessively abbreviated names.
• One-letter variable names are rarely descriptive, though some common exceptions include using i, j, and k for loop counters, n for the number of things, and x, y, and z for coordinates of points. (But don't feel obliged to use these names if you can think of better ones!)
• When loop counters can be named descriptively, they should be. (e.g. name the counter after what is being counted, instead of just calling it counter, count, or ctr)
• Use nouns or short noun phrases for variable names. Begin with a lowercase letter and capitalize the first letter of additional words. Examples: length, numSpaces
• Use verbs or short verb phrases for function names. Begin with a lowercase letter and capitalize the first letter of additional words. Methods which return boolean values should generally start with is. Examples: computeTotal, sort, isLegalValue
• While Processing is case-sensitive (i.e. sum and Sum are different identifiers), you should avoid using multiple names which differ only in case within the same scope. (This helps prevent errors caused by typos.)

Use whitespace to enhance readability:

• Put a blank line between functions.
• Group lines of code that accomplish a task together, putting blank lines before and after the chunk to distinguish it from the rest of the code.
• Indent to show the nesting level of curly braces.
• Break lines at or before 80 characters, and at a convenient place.
• Semi-colons (;) and both open and close curly brackets ({ and }) should generally be followed by a line break.

Use comments to explain things for the human reader:

• Include your name and the assignment in a comment at the top of each sketch.
• Include a description of what the sketch is and/or what its purpose is at the top of each sketch.
• Briefly describe the purpose of each variable when it is declared.
• Describe what each function does, including its parameters and return values, immediately before the function header.
• If you have distinct chunks of code that you've put blank lines around, include a comment describing what the chunk accomplishes at the beginning of the chunk.

80 Characters, Word Wrapping, and gedit

The editor gedit supports "text wrapping", which means it looks like there are no problems with long lines because they automatically wrap when you get to the edge of the editor window - but gedit is only displaying the lines as wrapped rather than actually inserting line breaks to split the lines. This means ugliness and unreadability when someone tries to print your file or open it with a different text editor.

To fix the problem, you should do the following in gedit:

• On the Edit menu, choose "Preferences".
• In the "View" tab, uncheck "Enable text wrapping" and check "Display right margin at column: 80". (Make sure the column is 80; change it if necessary.)
• Close the Preferences window.

You should now see a vertical gray line near the right side of the editor window. (If you don't see it, resize your window wider.) This line marks a width of 80 characters. Keep an eye on this line as you type - if you have text that would extend past it, put in a line break as needed to keep all text on the left side.

last updated: --Mon Dec 15 15:52:03 EST 2014-- page owned by: bridgeman@hws.edu