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: Sat, 16 Jan 2010 17:43:03 -0000
Message-ID: <20100116174303.28216.80437@eos.apache.org>
Subject: 
 =?utf-8?q?=5BHttpcomponents_Wiki=5D_Update_of_=22CodingConventions=22_by_?=
 =?utf-8?q?TonyPoppleton?=

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=3Ddiff&rev1=
=3D7&rev2=3D8

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

  ## page was renamed from CodingStandards
  =3D (Draft) Coding conventions =3D
  =

- ||<#FF8080> /!\ THESE CONVENTIONS ARE NOT OFFICIAL IN ANY WAY.  PLEASE IG=
NORE 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 NE=
VER 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 f=
or now ||
+ Why have coding conventions? Coding conventions are important to programm=
ers 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 a=
uthor.
+  * Code conventions improve the readability of the software, allowing eng=
ineers 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=
 warnings are there for a reason)
   * Don't supress any types of warnings (with the execption of generics wa=
rnings when using 3rd party code that you cannot modify)
+ }}}
  =

  =3D=3D Style =3D=3D
+ {{{
-  * {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", "jav=
ax", "org", "com" in that order, and within each block should be sorted alp=
habetically (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 alphabe=
tically (Note that Eclipse IDE does this automatically for you)
-  * {1} Use camelCase naming convention for classes/methods/fields/variabl=
es
+  * 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 Abst=
ract..., especially if it is the base implementation of an interface
-  * {3} Use a single blank line to separate code when appropriate; there s=
houldn'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 shoul=
dn'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 m=
ade 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 ha=
ve multiple lines
+  * Put braces around if blocks in any part of the if/else sections have m=
ultiple lines
+ }}}
  =

  =3D=3D Javadoc & comments =3D=3D
+ {{{
-  * {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 Java=
doc will add more than the obvious (for example getters and setters are sel=
f-explanitory)
-  * {3} Javadoc should only precede class, field, constructor or method de=
claration and should not appear anywhere else
+  * Javadoc should only precede class, field, constructor or method declar=
ation 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 commen=
ts - 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 wa=
s intentially left blank (although a more useful comment is also welcome)
+  * Mark empty blocks of code with a "//NOP" comment to document in was in=
tentially left blank (although a more useful comment is also welcome)
-  * {3} Use "//TODO" before the comment to mark possible improvements or r=
emaining tasks (Eclipse IDE will flag these comments)
+  * Use "//TODO" before the comment to mark possible improvements or remai=
ning tasks (Eclipse IDE will flag these comments)
-  * {3} Use "//HACK" before the comment to mark incomplete patches, fragil=
e code or poor solutions (Eclipse IDE will flag these comments)
+  * Use "//HACK" before the comment to mark incomplete patches, fragile co=
de or poor solutions (Eclipse IDE will flag these comments)
-  * {3} Use "//NOTE" before the comment to emphasize important comments, f=
or 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 e=
xample something counter-intuitive or unexpected like a for loop going back=
wards (Eclipse IDE will flag these comments)
+ }}}
  =

  =3D=3D Fields =3D=3D
+ {{{
-  * {1} Fields should appear at the top of the class, not declared half-wa=
y down the class
+  * Fields should appear at the top of the class, not declared half-way do=
wn the class
-  * {3} (TODO the following rule is not adhered to anywhere, but I would r=
ecommend it rather than using the this. prefix) All instance fields should =
start with the m prefix (this is also setup in the standard preferences). D=
on't use m prefix on local variables.
+  * (TODO the following rule is not adhered to anywhere, but I would recom=
mend it rather than using the this. prefix) All instance fields should star=
t with the m prefix. Don't use m prefix on local variables.
-  * {3} All static final fields should be capitalized, static non-final fi=
elds 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/fi=
nal)
+  * 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 sho=
uld be immutable)
+  * All fields in an enum should be final (i.e. all enum instances should =
be immutable)
+ }}}
  =

  =3D=3D Constructors =3D=3D
+ {{{
-  * {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 fie=
lds)
-  * {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 obj=
ect is not fully initialized yet (TODO link to corresponding Josh Bloch Eff=
ective Java Item number)
+ }}}
  =

  =3D=3D Exceptions =3D=3D
+ {{{
-  * {3} Use exceptions for exceptional circumstances
+  * Use exceptions for exceptional circumstances
-  * {3} Never simply print an exception to stderr or stdout, as the except=
ion 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 whi=
ch 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, fo=
r example, returning null from a method.
+  * Handle exceptional conditions by throwing an exception and not, for ex=
ample, returning null from a method.
-  * {3} Checked exceptions should represent potentially recoverable except=
ions; runtime exceptions should represent non-recoverable errors / unexpect=
ed errors / programming errors, as per [http://www.oracle.com/technology/pu=
b/articles/dev2arch/2006/11/effective-exceptions.html].
+  * Prefer unchecked exceptions (like RuntimeException) over checked excep=
tions as per [http://www.oracle.com/technology/pub/articles/dev2arch/2006/1=
1/effective-exceptions.html].  In summary, only use checked exceptions if i=
t is expected that the caller can handle it or recover from it.  Unchecked =
exceptions will just be propagated back to the general exception handler, w=
hich is ideal.
+ }}}
  =

  =3D=3D Collections =3D=3D
+ {{{
-  * {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 s=
ignificantly faster than Vector.
+  * For situations that do not require synchronization, ArrayList is signi=
ficantly faster than Vector.
-  * {3} For situations that do require synchronisation, use classes from t=
he Concurrent API if possible.  Vector is not enough on its own as the foll=
owing link explains [http://www.ibm.com/developerworks/java/library/j-jtp09=
263.html]
+  * For situations that do require synchronisation, use classes from the C=
oncurrent API if possible.  Vector is not enough on its own as the followin=
g link explains [http://www.ibm.com/developerworks/java/library/j-jtp09263.=
html]
+ }}}
  =

  =3D=3D JIRA integration =3D=3D
+ {{{
-  * {3} Comment a block of code with the JIRA reference if appropriate (es=
pecially for bug fixes), for example #HTTPCLIENT-1
+  * Comment a block of code with the JIRA reference if appropriate (especi=
ally for bug fixes), for example #HTTPCLIENT-1
-  * {3} When committing a patch, add the JIRA reference in the commit comm=
ent (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)
+ }}}
  =

  =3D=3D General =3D=3D
+ {{{
-  * {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 com=
ments when being cunning, so others don't inadvertently break the code by n=
ot 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 asse=
rt the obvious though as too many asserts impact readability
+  * Use assert to check assumptions where appropriate, no need to assert t=
he obvious though as too many asserts impact readability
-  * {3} Override both hashCode() and equals() when your object will be use=
d 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 fie=
ld/parameter/variable does not change during its scope, to document the int=
ent 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/p=
arameter/variable does not change during its scope, to document the intent =
that it should remain unchanged, and simply the lifecycle of the class/meth=
od 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 th=
umb...
+  * 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