Introduction
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)
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 (input<0) { return(Float.NaN); } / in the remainder of the method the value / of input will be greater or equal to 0 float ret=1; while (input>1) { 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.
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.
