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: [email protected] For additional commands, e-mail: [email protected]
