Programming Style
This page describes the minimum rules of programming style that you are required to follow. If you violate these guidelines, the grader can refuse to look at your code, resulting in no points for you. We reserve the right to add new rules as the semester progresses, but we'll always announce an update on the course mailing list before it goes into effect.
-
Indent your code consistently using either 2 or
4 spaces (not tabulators) for each nesting level; where you put
braces is really up to you, just put them consistently.
And please always put braces as part of
instructions like
ifandwhile, don't ever leave them out. - Make sure that your lines are at most 75 characters long, not any longer than that!
-
Follow the standard conventions for identifiers:
packages are
all.lower.case, classes areMixedUpperCaseand start with upper case, variables, functions, and procedures aremixedUpperCasebut start with lower case, constants areALL_CAPSwith underscores if needed; functions often (but not always) start with adjectives, procedures often (but not always) start with verbs. Also, the larger the scope of an identifier, the longer and more descriptive it should be; usingiinside a procedure is fine, usingiinside a class is not a good idea. - Comments inside your code should add information to the code, not repeat obvious things. Consider putting a comment for the purpose of each variable (unless the purpose is obvious), the larger the scope of a variable is the more important such a comment will be. And don't contradict your code!
- When hacking loops, avoid break and continue instructions as far as possible. If you think you need one, think again. If you still think you need one, include a comment that explains why. For methods, please avoid multiple return instructions as far as possible. However, since these are usually more benign (as long as your methods are not too long), there's no need to think as hard about them (but defending them in a comment is still encouraged).
-
Do not leave "magic numbers" like 9.81 and 42.7 in your code,
introduce useful names for them in some
finaldeclaration. Numbers that are okay to have are really basic ones like 0, 1, 2, and similar. -
Don't compare
booleanexpressions totrueorfalse: They are boolean already, no additional comparison needed, ever. They cannot very well become any "more boolean" in the process... -
As soon as you know how to write functions and procedures
(static methods that is) use them to
break up your code into sensible units. Don't write a
mainmethod that is 100 lines long; break sensible pieces out ofmaininto their own methods. Ideally, methods are never longer than 20 lines or so, but early in the course you don't yet have the tools to break them up. (Maybe think of methods as paragraphs in the overall story your program is telling.) -
Once
javadocis introduced, have at least onejavadoccomment for each class or interface and onejavadoccomment for each method. Follow the usual guidelines for writing these. They don't have to be essays but should be complete enough and clearly worded. Also, the comment itself is more important than using all the funkyjavadoctags...
Note that you're welcome to follow the official Code Conventions for the Java Programming Language as published by Sun instead of our minimal conventions, just make sure you tell us which conventions you follow. If in doubt, our minimum conventions are recommended because they are simpler.
