Dear Wiki user, You have subscribed to a wiki page or wiki category on "Httpcomponents Wiki" for change notification.
The "CodingConventions" page has been changed by TonyPoppleton. The comment on this change is: Updates according to feedback from Oleg and Sebb. http://wiki.apache.org/HttpComponents/CodingConventions?action=diff&rev1=7&rev2=8 -------------------------------------------------- ## page was renamed from CodingStandards = (Draft) Coding conventions = - ||<#FF8080> /!\ THESE CONVENTIONS ARE NOT OFFICIAL IN ANY WAY. PLEASE IGNORE THEM FOR NOW /!\ || + ||<#FF8080> NOTE THESE CONVENTIONS ARE STILL VERY PRELIMINARY AND ARE NOT OFFICIAL IN ANY WAY || + ||<#FF8080> PLEASE IGNORE THEM FOR NOW || + ||<#FF8080> THE ONLY CURRENT CONVENTION IS TO INDENT WITH 4 SPACES AND NEVER USE TABS || - The conventions are marked with the following symbols - || Symbol || Meaning || - || {1} || Must have convention. A failure to comply with the requirement may lead to the rejection of a patch || - || {2} || Should have convention. Recommended but not mandatory || - || {3} || Unapproved convention. Use when adding a new convention before it is officially signed off. Developers please ignore these conventions for now || + Why have coding conventions? Coding conventions are important to programmers for a number of reasons: + {{{ + * 80% of the lifetime cost of a piece of software goes to maintenance. + * Hardly any software is maintained for its whole life by the original author. + * Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly. + * Ensures consistency across the project, which is a good thing + }}} == Eclipse IDE == If you are using the Eclipse IDE for development, then it is recommended to download the following: + {{{ * Code formatter configuration (TODO link) * Cleanup configuration (TODO link) * TODO add this? .project and .classpath and .settings folders * Try and fix all the code warnings that Eclipse flags in your code (the warnings are there for a reason) * Don't supress any types of warnings (with the execption of generics warnings when using 3rd party code that you cannot modify) + }}} == Style == + {{{ - * {1} Ensure the Apache copyright header is at the top of every class + * Ensure the Apache copyright header is at the top of every class - * {3} Imports should be organized into blocks starting with "java", "javax", "org", "com" in that order, and within each block should be sorted alphabetically (Note that Eclipse IDE does this automatically for you) + * Imports should be organized into blocks starting with "java", "javax", "org", "com" in that order, and within each block should be sorted alphabetically (Note that Eclipse IDE does this automatically for you) - * {1} Use camelCase naming convention for classes/methods/fields/variables + * Use camelCase naming convention for classes/methods/fields/variables - * {1} All indentation should be done with 4 spaces; tabs should never be used + * All indentation should be done with 4 spaces; tabs should never be used - * {3} Lines should be wrapped if it improves readability + * Lines should be wrapped if it improves readability - * {3} The name of an "abstract" class should generally be prefixed with Abstract..., especially if it is the base implementation of an interface + * The name of an "abstract" class should generally be prefixed with Abstract..., especially if it is the base implementation of an interface - * {3} Use a single blank line to separate code when appropriate; there shouldn't be any more than one consecutive blank line in any part of the code + * Use a single blank line to separate code when appropriate; there shouldn't be any more than one consecutive blank line in any part of the code - * {3} Classes that are not explicitly designed for extension should be made final + * Classes that are not explicitly designed for extension should be made final - * {3} Put braces around if blocks in any part of the if/else sections have multiple lines + * Put braces around if blocks in any part of the if/else sections have multiple lines + }}} == Javadoc & comments == + {{{ - * {3} Write Javadoc at the class level + * Write Javadoc at the class level - * {3} Write Javadoc on public methods when appropriate, and only if the Javadoc will add more than the obvious (for example getters and setters are self-explanitory) + * Write Javadoc on public methods when appropriate, and only if the Javadoc will add more than the obvious (for example getters and setters are self-explanitory) - * {3} Javadoc should only precede class, field, constructor or method declaration and should not appear anywhere else + * Javadoc should only precede class, field, constructor or method declaration and should not appear anywhere else - * {3} Javadoc should wrap at 80 chars + * Javadoc should wrap at 80 chars - * {3} Comments in the code are also encouraged + * Comments in the code are also encouraged - * {3} Use "//" for all non-Javadoc comments, including multi-line comments - avoid the use of /**/ comment blocks. + * Use "//" for all non-Javadoc comments, including multi-line comments - avoid the use of /**/ comment blocks. - * {3} Mark empty blocks of code with a "//NOP" comment to document in was intentially left blank (although a more useful comment is also welcome) + * Mark empty blocks of code with a "//NOP" comment to document in was intentially left blank (although a more useful comment is also welcome) - * {3} Use "//TODO" before the comment to mark possible improvements or remaining tasks (Eclipse IDE will flag these comments) + * Use "//TODO" before the comment to mark possible improvements or remaining tasks (Eclipse IDE will flag these comments) - * {3} Use "//HACK" before the comment to mark incomplete patches, fragile code or poor solutions (Eclipse IDE will flag these comments) + * Use "//HACK" before the comment to mark incomplete patches, fragile code or poor solutions (Eclipse IDE will flag these comments) - * {3} Use "//NOTE" before the comment to emphasize important comments, for example something counter-intuitive or unexpected like a for loop going backwards (Eclipse IDE will flag these comments) + * Use "//NOTE" before the comment to emphasize important comments, for example something counter-intuitive or unexpected like a for loop going backwards (Eclipse IDE will flag these comments) + }}} == Fields == + {{{ - * {1} Fields should appear at the top of the class, not declared half-way down the class + * Fields should appear at the top of the class, not declared half-way down the class - * {3} (TODO the following rule is not adhered to anywhere, but I would recommend it rather than using the this. prefix) All instance fields should start with the m prefix (this is also setup in the standard preferences). Don't use m prefix on local variables. + * (TODO the following rule is not adhered to anywhere, but I would recommend it rather than using the this. prefix) All instance fields should start with the m prefix. Don't use m prefix on local variables. - * {3} All static final fields should be capitalized, static non-final fields should have an s prefix + * All static final fields should be capitalized, static non-final fields should have an s prefix - * {3} Make fields final when possible + * Make fields final when possible - * {3} Don't use public or protected fields (unless they are immutable/final) + * Don't use public or protected fields (unless they are immutable/final) - * {3} All fields in an enum should be final (i.e. all enum instances should be immutable) + * All fields in an enum should be final (i.e. all enum instances should be immutable) + }}} == Constructors == + {{{ - * {3} Constructors should be declared at the top of the class (below the fields) + * Constructors should be declared at the top of the class (below the fields) - * {3} Singleton constructors should be made private + * Singleton constructors should be made private - * {3} The constructor should not pass "this" to any other method, as the object is not fully initialized yet (TODO link to corresponding Josh Bloch Effective Java Item number) + * The constructor should not pass "this" to any other method, as the object is not fully initialized yet (TODO link to corresponding Josh Bloch Effective Java Item number) + }}} == Exceptions == + {{{ - * {3} Use exceptions for exceptional circumstances + * Use exceptions for exceptional circumstances - * {3} Never simply print an exception to stderr or stdout, as the exception will effectively just be lost. + * Never simply print an exception to stderr or stdout, as the exception will effectively just be lost. - * {3} In very rare cases it may be approriate to ignore an exception, in which case document it clearly. + * In very rare cases it may be approriate to ignore an exception, in which case document it clearly. - * {3} TODO is there a custom HTTP client exception that is used? + * TODO is there a custom HTTP client exception that is used? - * {3} Handle exceptional conditions by throwing an exception and not, for example, returning null from a method. + * Handle exceptional conditions by throwing an exception and not, for example, returning null from a method. - * {3} Checked exceptions should represent potentially recoverable exceptions; runtime exceptions should represent non-recoverable errors / unexpected errors / programming errors, as per [http://www.oracle.com/technology/pub/articles/dev2arch/2006/11/effective-exceptions.html]. + * Prefer unchecked exceptions (like RuntimeException) over checked exceptions as per [http://www.oracle.com/technology/pub/articles/dev2arch/2006/11/effective-exceptions.html]. In summary, only use checked exceptions if it is expected that the caller can handle it or recover from it. Unchecked exceptions will just be propagated back to the general exception handler, which is ideal. + }}} == Collections == + {{{ - * {3} Use classes from the Collections API such as ArrayList or HashMap over legacy classes such as Vector or Hashtable. + * Use classes from the Collections API such as ArrayList or HashMap over legacy classes such as Vector or Hashtable. - * {3} For situations that do not require synchronization, ArrayList is significantly faster than Vector. + * For situations that do not require synchronization, ArrayList is significantly faster than Vector. - * {3} For situations that do require synchronisation, use classes from the Concurrent API if possible. Vector is not enough on its own as the following link explains [http://www.ibm.com/developerworks/java/library/j-jtp09263.html] + * For situations that do require synchronisation, use classes from the Concurrent API if possible. Vector is not enough on its own as the following link explains [http://www.ibm.com/developerworks/java/library/j-jtp09263.html] + }}} == JIRA integration == + {{{ - * {3} Comment a block of code with the JIRA reference if appropriate (especially for bug fixes), for example #HTTPCLIENT-1 + * Comment a block of code with the JIRA reference if appropriate (especially for bug fixes), for example #HTTPCLIENT-1 - * {3} When committing a patch, add the JIRA reference in the commit comment (JIRA can then list the file under the "Subversion Commits" tab) + * When committing a patch, add the JIRA reference in the commit comment (JIRA can then list the file under the "Subversion Commits" tab) + }}} == General == + {{{ - * {3} Prioritize readability of code over speed/cunning code - flag with comments when being cunning, so others don't inadvertently break the code by not having spotted the subtlety. "Java files are for humans, class files are for the JVM" + * Prioritize readability of code over speed/cunning code - flag with comments when being cunning, so others don't inadvertently break the code by not having spotted the subtlety. "Java files are for humans, class files are for the JVM" - * {3} Use assert to check assumptions where appropriate, no need to assert the obvious though as too many asserts impact readability + * Use assert to check assumptions where appropriate, no need to assert the obvious though as too many asserts impact readability - * {3} Override both hashCode() and equals() when your object will be used in a Set/Map, and toString() is also useful + * Override both hashCode() and equals() when your object will be used in a Set/Map, and toString() is also useful - * {3} TODO remove this one? The "final" keyword should be whenever a field/parameter/variable does not change during its scope, to document the intent that it should remain unchanged, and simply the lifecycle of the class/method for other readers of the code + * TODO remove this one? The "final" keyword should be whenever a field/parameter/variable does not change during its scope, to document the intent that it should remain unchanged, and simply the lifecycle of the class/method for other readers of the code - * {3} Don't deprecate code unless there is an alternative method to use + * Don't deprecate code unless there is an alternative method to use - * {3} Consistency, standardization and simplicity are useful rules of thumb... + * Consistency, standardization and simplicity are useful rules of thumb... + }}} == Annotations == TODO use of jcip annotations like ThreadSafe etc. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
