Download CS 138 Coding Conventions: Naming and Formatting Rules for Java Programs - Prof. Thomas Do and more Study notes Computer Science in PDF only on Docsity!
CS 138: Coding Conventions
January 20, 2003
1 Purpose
When working on a large project, consistency is important. A decent coding convention helps make code clearer and ultimately makes code easier to debug and maintain. More importantly, it improves the readability for other people, which in this case are going to be the TAs who are going to be grading you, and when in doubt, easily readable code tends to be favored over spaghetti.
The coding convention presented here will allow you to uniquely identity global functions, member functions, class names, local variables/function arguments and global variables at a glance. Furthermore, these coding conventions will provide some protection from common mistakes that lead to tricky run-time errors. These are strong suggestions, but only sugges- tions - if you have an insurmountable personal bias about conventions you already use, feel free, but make sure it’s clear. (16 letter Hungarian prefixes or writing all of your code on one line, for example, are bad ideas.)
2 Naming Conventions
Classes Example: HelloWorld, MyClass Capitalize the first letter of the class name as well as the first letter of words in the class name.
Local Variables/Functions Example: helloWorld, myLocalVariable Capitalize the first letter of the words in the variable name except the first letter of the variable name.
Instance Variables Example: m helloWorld, m myMemberVariable Same style as local variables, except “m ” is prepended to the variable name.
Name Length Good: numBirds, totalCost Bad: nb, tc Opt for longer and more descriptive names, rather than short and ambiguous ones (except for loop variables, where “i” works just fine).
CS 138 Coding Conventions (2/3)
3 Formatting Conventions
Brace Placement Braces should be formatted according to “Allman style”. The opening brace should appear on a new line below the if, loop construct or function name, as shown below.
Indenting Indent the code between two braces with 4 spaces instead of a tab.
if( ) { while( true ) { ... } }
Comparison Equal (==) Good: 10 == i, abs(i) == i Bad: key == 4 Always have the function or constant on the left side of the ’==’, as this will lead to a compile-time error if you accidently type ’=’ instead of ’==’.
4 Java Language Conventions
java.* and import Err on the side of caution when importing - if you only need one class from a package, import it instead of the entire package.
constants Define interfaces in which you define constants and nothing else - this will give you an easy way to centralize your constants into a single location.
package Put all of your code into packages. Ideally every assignment, with the possible excep- tion of the third which builds on the second, should be part of a different package, for clarity. This should indicate to you early if there are problems with modularity in your designs.
assert Example: assert (numHeads < 1) and assert (funcReturningBoolean()) As of Java 1.4, the assert facility has been added to the language. Use assert to validate assumptions you make, such as that a function will not fail or that a variable is within some desired set of values. If the given expression is false, the assert fails and your program will stop with an error indicating the point of failure. Be aware that the syntax is different than in C++, and that assert will only operate on booleans, not integers. If you wish to use asserts, you must pass the -ea flag to java when executing a
January 20, 2003 Owner: Sean Cannella (scannell)
