In the "real world", it is not sufficient for code to just "work" - it also has to be easy for other people to read and understand, easy to extend later, and sufficiently clear that there are no hiding places for obscure bugs. For this reason, clear, readable code is a core requirement of the IJP course - code which is difficult to read will not pass, and higher marks require particularly clear and well-structured source code.
Different organisations and projects may adopt different conventions and "standards" to ensure that their code is consistent. In general, you will need to adapt your style to fit in with the project that you are working on. IJP does not enforce any particular style, but you must make sure that your style is consistent throughout your own code, and that it is clear. The following tips are intended to help you think about the readability of your code:
In general, your code itself should be sufficently clear that it does not require additional comments on every statement. Too many comments can make the code more difficult to read. You must judge for yourself what you think will make the code as clear as possible to a (similarly-experienced) reader. Some typical places where comments might be useful (essential?) are:
- at the top of each file to explain the overall purpose of the file/class.
- to explain the reason behind a statement (rather than what the statement does). For example: "Why does this statement add 10% to the tax" ?
- at the start of a method where the purpose and/or arguments may not be obvious.
- on variable declarations to explain the purpose of the variable.
Make sure that you comments are meaningful and up-to-date: if you copy and edit a template file, remember to delete/edit any comment which say "this is a template"!
Javadoc is a system for automatically generating documentation from structured comments in the source code. The online documentation for the standard Java libraries, and the IJP assignment libraries are automatically generated in this way. This is particularly useful for documenting libraries of public methods which are intended for use by other people.
For the IJP assignments, it is sufficient to provide consistent and clear comments (see above), and Javadoc is not required. However, if you would like to know more about Javadoc, or use it in your own code, the The BlueJ book has an appendix on Javadoc, and the FAQ explains how to generate the Javadoc from your source code. The Oracle website also has information on Javadoc.
Meaningful variable names go a long way towards helping others understand your code without additional comments. Choose these carefully, and be consistent in your use of case - we strongly recommend that you use the following conventions:
- methods: lowerCamelCase (addSubject, getPicture)
- classes: UpperCamelCase (MyCacheProxy, Controller)
- packages: lowercase (model, longpackagenamewithmultiplewords)
- constants: CONSTANTCASE (SPEEDOF_LIGHT, PI)
This does not mean that you should not use short names where appropriate: "x" and "y" are perfectly good names for the coordinates of a point, if there is only one point and the variables are used within a small scope. Similarly, "i" is a perfectly good name for a counter if the loop is short and the purpose is obvious. If the scope is larger, and the reader has to search for the variable declaration, then you probably need a more meaningful name.
The layout of the code (particularly the indentation) is critical for the reader to be able to understand the logic of your program. If conditionals or loops are incorrectly indented, then it is very easy for the reader to misinterpret the code - and this is very bad.
Eclipse makes it very easy to correct important layout errors by providing functions (in the Style menu) to correct the indentation and reformat sections of code. In addition to using these functions as necessary, you should review your code for a consistent layout style - for example the placement of the opening braces on methods.
All of the above suggestions refer to the small-scale syntax and layout of the code. When reading a larger program, the most difficult challenge is usually to understand how the code is structured and where to find the particular part of the code that performs a certain function. Writing code which is clear in this way takes more experience, and involves a consideration of the structure of the code itself, rather than just the surface features. Here are some things that you should consider ...
- make sure that the classes are as cohesive and loosely coupled as possible.
- make sure that each class is clearly commented with its purpose.
- avoid long and complicated methods or control structures - factor out their contents into individual methods with meaningful names and parameters.