Dinopolis Java Coding Convention

Transcription

1 Dinopolis Java Coding Convention Revision : 1.1 January 11, 2001 Abstract Please note that this version of the Coding convention is very much based on IICM s internal Dino coding convention that was used for the development of the predecessor of the Dinopolis library. As such it is very likely to be biased, therefore please post your comments in the discussion forum and help us improve it over time. It is important for a free software project with programmers distributed on the Internet that the code is easy to understand. If programmers follow a common coding convention and some fundamental design guidelines, this goal is easier to reach. If you modify code of others please follow the same convention and style that the original code uses. 1 General Rules The following principles strongly improve the readability and easy maintainance of source code: Simplicity: Also known as the KISS (Keep It Small and Simple) principle. In short this means that classes shall not have fat interfaces and methods shall fulfill exactly one atomic task according to their abstraction level. Intuitivity: In short this means that it shall be possible to read the code like a book and understand it without comments and explanations. Uniformity: In short this means that related pieces of code follow the same principles. For example methods doing the same shall be called the same throughout the code and take the parameters in the same order. As an example a method called copy that takes source and destination as parameters shall always take the parameters in the same order no matter which class implements such a copy method. 1.1 Simplicity of Code The following rules keep the code simple: Classes must not have fat interfaces. 1

2 Methods have to perform only one atomic task according to their abstraction level. Methods have to be as short as possible (as a rule of thumb not longer than 60 lines of code unless absolutely necessary, methods shorter than 60 lines of code are preferable). 1.2 Intuitivity of Code Following rules apply to keep the code intuitive: Variable names have to be self-explaining in a way that they describe exactly what they are standing for. As an example count stands for a counter variable. One-letter variables like i (as often used for counters) should be avoided. Method names have to be self-explaining in a way that they describe exactly what they are doing. As an example a method public boolean isaccessallowed() has to check if access is allowed and nothing else! If a method performs more than one task the name has to reflect that fact (although methods that perform more than one task are considered bad programming style and shall be avoided!). As an example public void spellcheckandcorrect(document doc) stands for a method that checks the spelling of doc and corrects it if necessary. In this case naming the method just public void spellcheck(document doc) would not reflect that this method also changes the document if necessary and therefore this name is not a good choice. Unnecessary comments are considered disturbing and should be omitted (e.g. // and here x is incremented). In fact comments in well-written code are mostly completely unnecessary. Only in very special cases if e.g. for performance reasons complicated code has to be written comments are necessary and therefore recommended. In this case the complicated algorithm has to be explained in a comment-block above the algorithm and comments in the running code shall be omitted if possible. 1.3 Uniformity of Code Following rules apply to keep code uniform: Methods that perform the same task are always called the same and take the same parameters (e.g. copy(src,dst)). It is bad programming style that a method s signature is e.g. copy(src,dst) in one class and e.g. copy(dst,src) in another! This also applies to the meaning of parameters: It is unwise to define a method int count() and another method int size() that both perform the same task, namely returning the number of elements. Variables that stand for the same are always called the same (e.g. length). This requirement is equal to the requirement for methods above. 2

3 2 Coding Conventions This section describes the coding conventions for the Dinopolis library. If you follow these rules and those described in the Design Guidlines it can be ensured that your code is easy to read, easy to understand and easy to modify which will make other programmers happy who have to deal with your code. The coding conventions deal with the way code is written. The design guidelines (=how code is written) can be found in the Dinopolis Design Guidlines. 1. The language for code is English. This applies for all names and identifiers in the code as well as for all comments. 2. The principles of simplicity, intuitivity and uniformity as described in section 1 should be followed. 3. Avoid the use of block comments (/* */) in the source code and use the line comments (//) instead. This makes the source code less fragile to erroreneous deletions of code-lines. 4. If it is absolutely necessary to put comments in the code to describe algorithmic details (see also section 1.2) preceed the according code fragment with a comment block rather than spreading the comments across the code fragment. 5. If it is absolutely necessary to clarify non-obvious code write short comments at the end of the appropriate code line. Nevertheless whenever such a comment seems necessary think twice if there is a better obvious solution that doesn t need a comment! 6. When describing a design pattern the name of the book which deals with this pattern should be cited (e.g. [Gamma et al. 1998]). 7. When describing algorithms the names of the book which deals with these algorithms and datastructures should be cited (e.g.[sedgewick 1992]. 8. The source code for every class (even for non-public classes) should reside in a file of its own. The only exception to this rule are inner classes and anonymous classes as it is per definition impossible to put them in files of their own. 9. When writing stand-alone programs the class with the main method in it should not have anything to do with the functional part of the code. The same applies for applets: The Applet class should not have anything to do with the functional part of the code. 10. Every class should be a member of a package. Classes belonging to the default package are undesired, even for testing. 11. Java import statements should be written in the following order: (a) Java Core API classes. (b) Java Extension API classes. (c) Classes from third party APIs. 3

4 (d) Dino classes. To increase the readability of the import part, all imports should be sorted by package names, that means imported classes belonging to the same package can be found in consecutive lines. Between the three categories mentioned above a single blank line is recommended. Using wildcards in import statements makes updating of classes hard and should therefore be avoided. 12. Classes should be preceded by a Javadoc header of the following form: /** * Description of the class in HTML format, if a useful link can * be given in the running text do this with fully.qualified.class#method(fully.qualified.param) <authorname> <version number> <fully.qualified.classname#methodname(param-classes)> <if applicable write reason here, otherwise omit * this line> */ class DExampleClass In the description text a usage example is highly recommended. 13. Prefix methods by a Javadoc header of the following form: /** * Description of the method in HTML format, if a link can * be given in the running text do this * fully.qualified.classname#methodname(fully.qualified.paramclass) <paramname> <paramdescription> <return value> <exception> <description when it is thrown> <fully.qualified.classname#methodname(param-classes)> <reason if applicable, otherwise omit this line> */ public Object myfunction(object test_param) throws MySpecialException In the description a usage example is highly recommended. 14. If bad hacks are absolutely unavoidable for whatever reason (e.g. absolutely have to meet a deadline, etc..) they should be tagged by a hack-start and hack-end comment of the following form: 4

5 // FIXXME (<author, date>) -> <description of the hack> [.. the hack..] // END FIXXME (<author, date>) To facilitate a grep, the keyword FIXXME should be written in upper-case and with at least two X s. More than two are allowed and should be used for really bad hacks - as a rule of thumb: the more X s the word FIXXME contains the worse the hack is, up to a maximum of five X s. All hacks that have found their way into the code should be removed as soon as possible! 15. Name dentifiers according to the following naming conventions: Packages: lowercase Classes: AllWordsCapitalizedWithoutUnderscores Methods: firstwordlowercaserestcapitalizedwithoutunderscores Constants (=finals): ALL UPPER CASE WITH UNDERSCORES Class and instance member variables: all lower case with underscores and with trailing underscore Auto variables (=variables used locally in methods): all lower case with underscores Exceptions: ClassNameEndsWithException Besides these general naming rules some special naming conventions apply: All Classes in the Dino core package should start with D to make them distinguishable from classes of other packages and to avoid name-clashes. The only exception to this rule applies when working with factories that can also be extended from third party application programmers. In this case the classes must not start with a D. All methods which change properties of classes should be named setxxx. The methods returning the value of certain properties of classes can be divided into two categories: getxxx for non-boolean properties and isxxx for boolean values respectively. Example: public void setcounter(int value) public int getcounter() 5

6 public void setreadonly(boolean value) public boolean isreadonly() 16. The following code structuring conventions apply: Write curly braces around code-blocks in lines of their own. Indent code-blocks by two spaces. Don t use tabs for indentations but use spaces instead. Only indent the code block, not the curly braces! When invoking methods the opening brace always should follow the method name without any whitespaces. Preceed every method definition with the following comment line to make the code more readable: //

7 References [Gamma et al. 1998] Gamma E., Helm R. Jonson R. Vlissides J.: Design Patterns - Elements of Reusable Object-Oriented Software, Addison Wesley (1999). [Sedgewick 1992] Sedgewick R.: Algorithms, Addison Wesley (1992). end of document 7