Mailing-List: contact dev-help@hc.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "HttpComponents Project" <dev@hc.apache.org>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Fri, 15 Jan 2010 18:30:24 -0000
Message-ID: <20100115183024.2937.62987@eos.apache.org>
Subject: 
 =?utf-8?q?=5BHttpcomponents_Wiki=5D_Update_of_=22CodingStandards=22_by_To?=
 =?utf-8?q?nyPoppleton?=

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:
=3D (Draft) Coding conventions =3D

Why have coding conventions? Coding conventions are important to programmer=
s 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 aut=
hor.
 * Code conventions improve the readability of the software, allowing engin=
eers to understand new code more quickly and thoroughly.
 * Ensures consistency across the project, which is a good thing
}}}

=3D=3D Eclipse IDE =3D=3D
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 w=
arnings are there for a reason)
 * Don't supress any types of warnings (with the execption of generics warn=
ings when using 3rd party code that you cannot modify)
}}}

=3D=3D Style =3D=3D
{{{
 * 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 alphabeti=
cally (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 Abstra=
ct..., 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 fi=
nal
 * Put braces around if blocks in any part of the if/else sections have mul=
tiple lines
}}}

=3D=3D Javadoc & comments =3D=3D
{{{
 * Write Javadoc at the class level
 * Write Javadoc on public methods when appropriate, and only if the Javado=
c will add more than the obvious (for example getters and setters are self-=
explanitory)
 * Javadoc should only precede class, field, constructor or method declarat=
ion 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 - a=
void the use of /**/ comment blocks.
 * Mark empty blocks of code with a "//NOP" comment to document in was inte=
ntially left blank (although a more useful comment is also welcome)
 * Use "//TODO" before the comment to mark possible improvements or remaini=
ng 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 exa=
mple something counter-intuitive or unexpected like a for loop going backwa=
rds (Eclipse IDE will flag these comments)
}}}

=3D=3D Fields =3D=3D
{{{
 * 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 recomme=
nd 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 u=
se m prefix on local variables.
 * All static final fields should be capitalized, static non-final fields s=
hould 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)
}}}

=3D=3D Constructors =3D=3D
{{{
 * Constructors should be declared at the top of the class (below the field=
s)
 * Singleton constructors should be made private
 * The constructor should not pass "this" to any other method, as the objec=
t is not fully initialized yet (TODO link to corresponding Josh Bloch Effec=
tive Java Item number)
}}}

=3D=3D Exceptions =3D=3D
{{{
 * Use exceptions for exceptional circumstances
 * Never simply print an exception to stderr or stdout, as the exception wi=
ll 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 exam=
ple, returning null from a method.
 * Prefer unchecked exceptions (like RuntimeException) over checked excepti=
ons.  Only use checked exceptions if it is expected that the caller can han=
dle it or recover from it.  Unchecked exceptions will just be propagated ba=
ck to the general exception handler, which is ideal.
}}}

=3D=3D Collections =3D=3D
{{{
 * Use classes from the Collections API such as ArrayList or HashMap over l=
egacy classes such as Vector or Hashtable.
 * For situations that do not require synchronization, ArrayList is signifi=
cantly faster than Vector.
 * For situations that do require synchronisation, use classes from the Con=
current API if possible.  Vector is not enough on its own as the following =
link explains [http://www.ibm.com/developerworks/java/library/j-jtp09263.ht=
ml]
}}}

=3D=3D JIRA integration =3D=3D
{{{
 * Comment a block of code with the JIRA reference if appropriate (especial=
ly for bug fixes), for example #HTTPCLIENT-1
 * When committing a patch, add the JIRA reference in the commit comment (J=
IRA can then list the file under the "Subversion Commits" tab)
}}}

=3D=3D General =3D=3D
{{{
 * Prioritize readability of code over speed/cunning code - flag with comme=
nts 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 f=
or 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...
}}}

=3D=3D Annotations =3D=3D
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