| CPSC 120 |
Principles of Computer Science |
Spring 2010 |
CPSC 120 Programming Standards
Consider a paper you are writing for some 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 HTML or
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, for example. The spacing
and font has 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.
HTML
Put in line breaks so that lines do not extend past 80 characters.
Use indentation to show nested tags. One exception is tags nested
within <body> ... </body>.
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)
- 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 kate
The editor kate supports "dynamic word wrap", which means it
looks like there are no problems with long lines - but kate
is only displaying the lines as wrapped rather than actually inserting
line breaks to split the lines. This means uglyness and unreadability
when someone tries to print your file or open in a different size
editor window.
To fix the problem, you should do the following in kate:
- On the View menu, make sure "Dynamic Word Wrap" is turned off (no
X next to the menu item). Choose it if you see an X.
- On the View menu, choose "Show Static Word Wrap Marker". This
should make a vertical line appear towards the right end 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 the static word wrap marker line as you type. If you
have a line that would extend past the marker, put in a line break
as needed to keep all text to the left of the marker.