[Httpcomponents Wiki] Update of "CodingStandards" by TonyPoppleton

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Httpcomponents Wiki" for change notification.

The "CodingStandards" page has been changed by TonyPoppleton.
http://wiki.apache.org/HttpComponents/CodingStandards

--------------------------------------------------

New page:
= (Draft) Coding conventions =

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 ==
{{{
 * Ensure the Apache copyright header is at the top of every class
 * 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)
 * Use camelCase naming convention for classes/methods/fields/variables
 * The name of an "abstract" class should generally be prefixed with Abstract..., especially if it is the base implementation of an interface
 * 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
 * Classes that are not explicitly designed for extension should be made final
 * Put braces around if blocks in any part of the if/else sections have multiple lines
}}}

== Javadoc & comments ==
{{{
 * Write Javadoc at the class level
 * 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)
 * Javadoc should only precede class, field, constructor or method declaration and should not appear anywhere else
 * Javadoc should wrap at 80 chars
 * Comments in the code are also encouraged
 * Use "//" for all non-Javadoc comments, including multi-line comments - avoid the use of /**/ comment blocks.
 * Mark empty blocks of code with a "//NOP" comment to document in was intentially left blank (although a more useful comment is also welcome)
 * Use "//TODO" before the comment to mark possible improvements or remaining tasks (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)
 * 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 ==
{{{
 * Fields should appear at the top of the class, not declared half-way down the class
 * (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.
 * All static final fields should be capitalized, static non-final fields should have an s prefix
 * Make fields final when possible
 * Don't use public or protected fields
 * All fields in an enum should be final (i.e. all enum instances should be immutable)
}}}

== Constructors ==
{{{
 * Constructors should be declared at the top of the class (below the fields)
 * Singleton constructors should be made private
 * 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 ==
{{{
 * Use exceptions for exceptional circumstances
 * Never simply print an exception to stderr or stdout, as the exception will effectively just be lost.
 * In very rare cases it may be approriate to ignore an exception, in which case document it clearly.
 * TODO is there a custom HTTP client exception that is used?
 * Handle exceptional conditions by throwing an exception and not, for example, returning null from a method.
 * Prefer unchecked exceptions (like RuntimeException) over checked exceptions.  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 ==
{{{
 * Use classes from the Collections API such as ArrayList or HashMap over legacy classes such as Vector or Hashtable.
 * For situations that do not require synchronization, ArrayList is significantly faster than Vector.
 * 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 ==
{{{
 * Comment a block of code with the JIRA reference if appropriate (especially for bug fixes), for example #HTTPCLIENT-1
 * When committing a patch, add the JIRA reference in the commit comment (JIRA can then list the file under the "Subversion Commits" tab)
}}}

== General ==
{{{
 * 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"
 * Use assert to check assumptions where appropriate, no need to assert the obvious though as too many asserts impact readability
 * Override both hashCode() and equals() when your object will be used in a Set/Map, and toString() is also useful
 * Don't deprecate code unless there is an alternative method to use
 * Consistency, standardization and simplicity are useful rules of thumb...
}}}

== Annotations ==
TODO use of jcip annotations like ThreadSafe etc.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org