-
Notifications
You must be signed in to change notification settings - Fork 12
Code style
This page briefly discusses code style in BoneJ.
Formatting should be consistent across files. This is somewhat difficult to achieve if developers use different IDEs, because of their differing auto formatting settings. One can export and import these settings between the different installations of the same application, but across IDEs it's challenging. In my experience even when you have the Eclipse code formatter plug-in installed on IntelliJ, the resulting formatting doesn't quite match the original on Eclipse. For more information, see this wiki page.
Despite these difficulties it's worth configuring your IDE to use a suitable auto formatting profile, and apply it consistently to all your source code files.
Code should aim for brevity instead of verbosity, but not to the point of using obscure single character variable names etc. You should avoid duplicating code, and extra qualifiers such as this when unnecessary. You should also omit initiliazations such as private boolean invert = false because in Java boolean fields are false by default. This way it's easier to spot the variables that are different, that require special attention. Complex real world project tend to accumulate large code bases over time, which are even more difficult to browse if the developers have not aimed for succinct, brief expression.
Comments should be reserved for things that are not readily apparent from the source code. For example, they can explain design choices, reason why a certain type of data structure was chosen, or why a certain line shouldn't be changed. However, having comments that explain what your code does can often be a sign that you should refactor the source. The ideal is to write self-documenting code. To put it shortly: "code tells you how, comments tell you why".
At least all public methods, fields and classes should have Javadoc. The Javadoc must be valid HTML and complete. That is, there can't be missing @param or @return tags or other such omissions. Invalid Javadoc will make a build fail on Travis. It's advisable to add documentation to some private members as well, as it's hard to remember even what one's own code does a few months after writing it. Since Javadoc supports HTML, it allows better notation for math then regular comments. For example, a vector component v_x becomes vx.
Members should be ordered so that first come all the fields of a class, then the methods, and finally sub-classes. Then these should be sorted according to their visibility. BoneJ follows the ordering presented in the ImageJ wiki. Finally, methods of the same visibility etc. should be sorted alphabetically. Keeping the order consistent across the source files, makes it easier to find a specific part.
Readability is especially important for reusable, open-source code, because it has to be accessible for a large number of developers. You don't want to stop people from adopting your code, because they can't figure out what it's doing. If we wish to contribute our algorithms to imagej-ops and other parts of the platform, other people need to be able to decipher their purpose so that they can help us maintain them.
Readability consists mainly of simple things like sensible variable names, avoiding magic numbers, structuring code into small enough classes and those classes into brief methods. Furthermore you should try to use existing code from various libraries instead of trying to rewrite algorithms yourself. The source files shouldn't contain commented out, "place holder" code either. In principle, isn't it easier to read text that divided into paragraphs, and written neatly? That doesn't have lots of notes in the margins, and smudged out sentences? That's written in short, punctuated and simple sentences?