hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Httpcomponents Wiki] Update of "CodingConventions" by SebastianBazley
Date Sat, 05 Jan 2013 20:26:40 GMT
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 SebastianBazley:
http://wiki.apache.org/HttpComponents/CodingConventions?action=diff&rev1=8&rev2=9

Comment:
Additional tweaks

  
  == Fields ==
   * {1} Fields should appear at the top of the class, not declared half-way down the class
+  * {3} Fields should appear in the following order: static, then instance. Group fields
with the same qualifiers together if possible.
   * {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.
-  * {3} All static final fields should be capitalized, static non-final fields should have
an s prefix
+  * {3} All static final fields should be capitalized, static non-final fields should have
an s prefix (but avoid these as they are inherently thread-hostile)
   * {3} Make fields final when possible
   * {3} 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)
@@ -53, +54 @@

  == Constructors ==
   * {3} Constructors should be declared at the top of the class (below the fields)
   * {3} 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)
+  * {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).
For the same reason: ctors should not start a thread, nor should they invoke overrideable
methods.
+ 
  
  == Exceptions ==
   * {3} Use exceptions for exceptional circumstances
@@ -61, +63 @@

   * {3} 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?
   * {3} Always try and add a useful message to the exception in case any one encounters it,
containing for example any runtime data that can be used to diagnose the exception
+  * {3} Document the exception and what causes it in the Javadoc (using @throws)
   * {3} 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].
  
@@ -78, +81 @@

   * {3} 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
   * {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
-  * {3} Don't deprecate code unless there is an alternative method to use
+  * {3} Don't deprecate code unless there is an alternative method to use; ensure the @deprecated
tag documents what the replacement is
   * {3} Consistency, standardization and simplicity are useful rules of thumb...
+  * {3} Where a method returns a collection or array, if there are no valid entries return
an empty collection or array rather than returning null. Use exceptions for errors. This simplifies
code, as there is no need to check for null before iterating over the response.
  
  == Annotations ==
  TODO use of jcip annotations like ThreadSafe etc.
+  * {3} Don't use the following SVN tags: @author (not useful for collaborative code), @date
(causes problems when comparing SVN with source archive). @version or @id is sufficient.
  

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


Mime
View raw message