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