Hi,
I'd like to submit some code for HttpClient but find I need to know the
coding conventions. I would like to formalize them and set up a coding
conventions web page.
I propose the following (which have been extracted mostly from existing code
and does not reflect my preferences) :
1/ Brackets. On the same line for class and method declaration (although I
prefer on the next line). On the same line for if, while, for, ....
*Mandatory* even for single line statements
2/ Spaces. Keywords followed by a parenthesis should be separated by a space
(ex: "while (true)"). Blank space should appear after commas in argument
lists. Binary operators should be separated from their operands by spaces
(ex: "a = (a + b) / c;")
3/ Indentations. 4 spaces, *NO* tabs.
4/ Javadoc for all class members including private ones. Javadoc need to be
explicit. for example, for the method "parseHeaders()", do not say "Parses
the headers" but rather something like "Parses the HTTP headers returned in
the response from the remote server"
5/ License. License at the top of each file
6/ Author references. Format : "@author <a
href="mailto:[EMAIL PROTECTED]";>John Doe</a>". Add your name below the
existing ones.
7/ Classes variables. No prefix but referenced using "this"
8/ Parameter names. Prefixed with "a". Ex: "public void someMethod(String
aName)". [I actually used "the" as prefix for Cactus].
9/ Line length. Max 80 chars as much as possible. Not sure if it makes sense
nowadays ?
10/ Versioning. All classes need to have a @version tag as follows :
"@version $Id: coding_conventions.xml,v 1.2 2001/08/19 17:03:05 vmassol Exp
$". Regarding the orders of tags, I propose :
11/ Format of classes :
"
<license text>
<package name>
[blank line]
<imports>
[blank line]
<beggining of javadoc for class>
<javadoc comments>
[blank line]
<author tags>
[blank line]
<version tag>
<end of javadoc for class>
"
12/ Logging.
12a/ Do not use System.out to log. Instead, use the logging facade. Use the
name of your class as the Log4j Category.For example :
private static final Log log =
LogSource.getInstance(HttpURLConnection.class.getName());
public void someMethod()
{
this.log.debug("some debug text");
}
12b/ Try as much as possible to log entry and exits of methods with the
parameter values. Our logging facade should include 2 additional methods :
logger.entry() and logger.exit() (which uses debug() calls and prefix the
message with respectively "<" and ">"), used as follows :
public void someMethod(String theClassName)
{
this.log.entry("someMethod([" + theClassName + "])");
[...]
this.log.exit("someMethod");
}
This will translate in the following log :
3435 [ApplicationServerThread] DEBUG some.package.MyClass -
>someMethod([SomeClassName])
3436 [ApplicationServerThread] DEBUG some.package.MyClass - <someMethod
12c/ Whenever logging a value, enclose it between square brackets as in :
this.log.debug("Name = [" + name + "]"); This permits detection of hard to
find bugs resulting of extra white spaces for example and is more readable.
12d/ If there is no value in logging the parameters (for example because the
object passed as parameter do not have a string representation and you
cannot add one), use the following :
public void someMethod(InputStream theInputStream)
{
this.log.entry("someMethod(InputStream)");
[...]
this.log.exit("someMethod");
}
That will differentiate the call from other calls to the same method name
but with different signature.
I think that's all and probably enough. If we set too many rules, they won't
be followed :)
Can you vote on that so that we can homogeneise our code and I can follow
the rules when submitting changes ?
Also, do you think we could propose a standard coding convention for the
whole of jakarta-commons ?
Thanks
-Vincent
