by CS112 TAs
Dear students,
Here are some hints on style when writing your programs to help you avoid losing
points. Remember that your programs must not just *work* (correctly), they
must also be understandable (and even pleasant) to read.
Get your indentation right and line up the indentation of beginning and ending brackets around blocks of code. It actually doesn't matter too much exactly what style you adopt for your indentation or placement of brackets around code blocks, but it should make it easy to read the code and you must be *consistent throughout all your programs*.
Within a method, leave a blank line between blocks of code to increase readability, for example between an "if/else" statement or a "for" loop and the next bunch of statements; or between the declarations of variables and the rest of the statements of the method. Also, leave one or two blank lines between each method definition.
Keep your lines of code less than 80 characters long. If you're using Windows this might be easy to forget, but traditionally, when programs are printed out or viewed in editors such as those on the Pantheon, lines with more than 80 characters tend to wrap around, messing up the indentation and making it hard to read.
When naming variables, use descriptive names, like "checkNumber" and "owedAmount" instead of "A" and "B". DO NOT use all capital letters for names of variables-- use them only for constants. Also use descriptive names for your methods.
Comment wisely. At the top of each method, put a comment summarizing what the method does, how it works, and what parameters it expects. Within each method, comment major or critical blocks of code. Do not, however, over-comment by writing an essay when a single line of code is clear enough to understand already.
To decide whether a method is too long and whether it should
be broken down into two or more methods, a common rule of thumb is that the
method should not be longer than one or two screens of text (i.e. about 50
lines). If your method is much longer than that, chances are you're trying to
take care of too much functionality in a single method. Try
breaking it down into smaller pieces, each which accomplishes a simpler part
of solving the problem.
Avoid using "break" statements except in the cases of a "switch" statement. If you are using a "while" or "for" loop and a bunch of "break"s inside of it, there is most probably a more intuitive, shorter and/or cleaner way to restructure your code so that you don't use them.
Don't overuse arrays. Arrays are great for some purposes, but trying to solve every problem using them can lead to contorted and long solutions.
Assignments are not meant to kill you (I don't think :-) ). If
you are spending more than 10 hours on trying to figure something out, then
that's really kind of too much; so ask a question to the newsgroup, or contact
the TAs or the professor.
--- CS112 TAs
Last updated: 10/14/2002 09:51:02 -0400