COMP284 Coding Standard
This standard defines how your code should be styled for assignments and projects while
studying here in the department. By following these conventions, you will produce code
which is more readable and easier for you or someone else to follow. These guidelines apply
to all programming languages. The examples are shown in Java. Being able to write clean
legible code will also improve your employability.
Identifiers
Variables/Attributes
Identifiers for all attributes and variables should be meaningful and if appropriate contain
its own unit of measure. The unit of measure helps in understanding how to use it without
reading the comments. Variables/attributes should always start with a lower case letter.
Always use camel case to help aid reading of identifies, so an upper-case letter is introduced
for every new word.
Examples:
float weightInKilos; float heightInMetres; float delayInMilliseconds;
Class Identifiers
Class identifiers always start with an uppercase letter and should always be a noun. So,
Encryption is not a good name but Encryptor or EncryptionHelper are fine.
Examples:
Person Doctor Appointment
Constants
Identifiers of constants should always be expressed in uppercase, unless and only unless
there is a necessary convention to use lowercase (for example to distinguish between g (ac-
celeration due to earth’s gravity and G the universal gravitational constant). For constants
underscores are used to separate words.
Examples:
public static final float PI=3.149265445;
public static final int COLUMNS=10;
Method Names
Method names should start with a lower case letter and then follow camel case. All method
names should be verbs.
Examples:
public static int add(int a, int b)
public static int checkTwoEqual(int[] array)
Comments
The code should ideally be what is termed self-documenting, that is it is simple enough to
understand without keeping on referring to the comments. If the code is hard to follow then
it should be simplified and in some cases broken up.
Comments must always precede the part of the code that they refer to. Comments should
not go over the right hand side of the edit window. If a comment is too long, then it should
be broken down over several lines.
Javadoc
All comments in Java programs should follow the Javadoc format, this allows code docu-
mentation to be generated automatically.
Class Comments
All classes should start with a preamble describing the purpose of the class, what data it
stores and what services it provides, so that a user of the class can quickly determine how to
use the said class.
Method Comments
At a minimum each public method in a class should be commented. This is vital since the
public methods are the public interface to the code. Each method should have comment to
both the input variables and the returned values (if there are any).
Example:
/**
* Calculates the factorial of a number
* @param input Number to be factorialed
* @return Factorial of input
*/
public Float factorial(int input) {
// invalid negative input
if (input1) {
ret=ret*input;
input--;
}
return(new Float(ret));
}
Use of On-line Resources and Textbooks
If in the preparation of your code you have used specific ideas or code fragments that you
have found on-line or in a textbook, then you must include references to those source in your
comments and indicate clearly which part of the code is based on those. The reference must
be precise:
• If you have used a textbook then you must point to the specific page, pages, or figure that
you have used.
• If you have used an answer to a question on, say, stackoverflow, then you must point to
that specific answer, including a URL to that answer.
Examples:
/*
* The code for the following readFile function has been taken from
* erickson (http://stackoverflow.com/users/3474/erickson):
* How to create a Java String from the contents or a file?
* Stack Exchange Network, 16 May 2016.
* http://stackoverflow.com/a/326440 [accessed 30 October 2017].
* User contributions licensed under cc by-sa 3.0
* https://creativecommons.org/licenses/by-sa/3.0/
*/
static String readFile(String path, Charset encoding)
throws IOException {
byte[] encoded = Files.readAllBytes(Paths.get(path));
return new String(encoded, encoding);
}
/*
* The code for the following keywordSearch function has been taken
* from Figure 9.8 on page 307 of
* R. Morelli and R. Walde: Java, Java, Java: Object-Oriented Problem
* Solving (Third Edition). Pearson, 2005.
* Available at http://www.cs.trincoll.edu/~ram/jjj/jjj-os-20170625.pdf
* [accessed 30 October 2017]
* under Creative Commons Attribution 4.0 International License (CC BY 4.0)
* https://creativecommons.org/licenses/by/4.0/
* The variable name "ptr" in the source has been replaced by "pointer".
*/
public String keywordSearch(String s, String keyword) {
String resultStr = "";
int count = 0;
int pointer = s.indexOf(keyword);
while (pointer != 1) {
++count;
resultStr = resultStr + pointer + " ";
pointer = s.indexOf(keyword, pointer + 1);
}
resultStr = count + " : " + resultStr;
return resultStr;
}
Such attribution is required under the licenses that apply to the sources used in the examples
as well as the Academic Integrity Policy of the University.
Indentation and Braces
All code should be indented in a consistent way in order to correctly convey the program
structure. The indentation should not be excessive otherwise the code become unwieldy and
hard to read, so 3 white spaces is fine.
The placing of braces should follow the one true brace style. (1TBS): Constructs that allow
insertions of new code lines are on separate lines, while constructs that prohibit insertions are
on one line. Where it does not change the semantics, do use braces for a control statement
with only a single statement in its scope.
Examples:
public void evaluateBodyMassIndex (int bodyMassIndex) {
// Just one statement in the scope of this control statement
// but we still use braces
if (bodyMassIndex >= 30) {
System.out.println("This patient is obese");
}
}
if (x < 0) {
y = -1 * Math.round(x * -1);
} else {
y = Math.round(x);
}
Note that for JavaScript. there is a particularly good reason to follow 1TBS: JavaScript
uses automatic semicolon insertion. For example, JavaScript. adds a semicolon after return,
if it is followed by a newline. This means the two statements in the example below have
different meanings.
Examples:
// This returns an object literal
return {
name: ’Jane’
}
// This is an empty return statement followed by an object literal
return
{
name: ’Jane’
}
Conclusion
Following this guidance will make your code easier to understand and follow and will help
you debugging and maintaining your code.