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 Sun, 06 Jan 2013 12:00:59 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=9&rev2=10

Comment:
Some more on comments

  == Javadoc & comments ==
   * {3} 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)
+  * {3} Use @since markers on classes / methods to show the version where they were introduced
+  * {3} Use the @deprecated marker to show in which version the item was first deprecated
as well as the replacement to be used: e.g. @deprecated (4.2) use {@link URIBuilder}.
-  * {3} Javadoc should only precede class, field, constructor or method declaration and should
not appear anywhere else
+  * {3} Javadoc should only precede class, field, constructor or method declarations and
should not appear anywhere else
   * {3} Javadoc should wrap at 80 chars
-  * {3} Comments in the code are also encouraged
+  * {3} Comments in the code are also encouraged.
+  * {3} Don't rely on users being able to read the SVN log comments. Log comments are not
permanent and are not provided to end users so should only be used to explain the commit message.
Additional comments should be added to the code as necessary so that it is clear without needing
to refer to the log comments.
   * {3} 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 was intentially left
blank (although a more useful comment is also welcome)
   * {3} Use "//TODO" before the comment to mark possible improvements or remaining tasks
(Eclipse IDE will flag these comments)
@@ -81, +84 @@

   * {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; ensure the @deprecated
tag documents what the replacement is
+  * {3} Don't deprecate code unless there is an alternative method to use
   * {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.
  

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


Mime
View raw message