You are viewing a plain text version of this content. The canonical link for it is here.
Posted to soap-dev@xml.apache.org by Sanjiva Weerawarana <sa...@watson.ibm.com> on 2000/11/15 13:01:05 UTC
Re: coding conventions and printing to System.err [READ THIS!]
[ARGH, I pressed the wrong button too early. ARGH. Please ignore the
previous message and read this!]
I was just looking through some of the recently committed code and I
see some problems that we as committers need to avoid now and not
later. I know we're putting our effort on the 3.0 codebase, but as
long as the other one is the live version we need to be careful about
the code we commit.
- handling exceptions by printing to stderr and returning null
This just won't do on the server side .. the code must do proper
error propagation or the whole thing becomes unusable.
Can each person please check and correct their code if needed?
(I'm assuming there's no disagreement on this topic!)
If you do put print stmts to debug while developing, then please
remove those before committing the code.
- coding styles
We each have our own coding style obviously. However, we're working
on a shared repository, so IMO we need to follow a single convention
as much as possible. I propose the following:
- maintain the 80 characters per line rule: if its longer break the
line
- upper/lower casing of variables/method/classes: follow the standard
Java conventions
- indentation: I suggest we keep to 2 spaces per nesting level. In
any case, no tabs. In any case, *please* indent .. don't put
things on the same line because we can .. Java is free-form and
using that free-form ends up in a more maintainable codebase.
- placement of "{" and "}": my preferred convention is to put the
"{" at the end of the previous thing:
if (foo bar) {
...
}
and the "}" on a line by itself, except for if-then-else. This is
most religious amongst people (Matt for example insists on doing it
the wrong way) and as such I suggest that we keep to exactly one
convention in a single file. That is, if I started editing the file
then it'll be done as above (i.e., the right way :-)) and if Matt
started it then it'll be done the wrong way. In either case, when
someone adds new code it should follow the convention that's established
for that file. If someone is essentially taking over the entire file,
then that person can do it their way.
- old code when new code is added
When some new code is committed the old code should be removed, not
commented out. If something goes wrong we always have the older version
to go back to, so there's no need to comment out and keep stuff.
- comments
We are a diverse group of people working on this code. As such,
comments are an absolutely necessary part of the code! I suggest that
everyone put a class-level comment telling what the class does etc.
and puts as much inlined comments as possible documenting the code.
I hope this doesn't come out the wrong way .. I'm not trying to "control"
this codebase - we have a working, stable codebase and we're making
incremental changes to it (a good thing). Keep it working and stable will
(IMO) require following some degree of discipline ..
Sanjiva.
Re: coding conventions and printing to System.err [READ THIS!]
Posted by Jean-Noel Gadreau <jn...@activcard.com>.
+1 for 4 spaces. I think that is a usual convention in Java, with tab
equivalent to 8 spaces.
Jean-Noel
Ryo Neyama wrote:
>
> > Agreed on all counts, including the right way to do braces :), except I
> > personally really dislike 2-space indents; I think 4 spaces is a) more
> > standard in the Java world, and b) much more readable. As with brace style,
> > I'd say stick to a single style per file in any case.
> >
> > I wouldn't suggest changing the existing code that uses 2-space indents, but
> > I'd vote for 4 on all future code.
> >
> > --Glen
>
> I agree with Glen. Generally speaking(I know you must know), it's not
> good idea that there are too deep indentations in one method. When the
> indent becomes too deep, we should re-design the class and separate it
> into multiple methods by the functionality. In that sense, 4 spaces
> would be better than 2 spaces, because it can prevent the too deep
> indentations.
>
> BTW, the Linux kernel code convention recommends 8 spaces for that
> reason, although I think it's not good for us.
>
> Regards,
> Ryo Neyama @ IBM Research, Tokyo Research Laboratory
> Internet Technology
> neyama@trl.ibm.co.jp
Re: coding conventions and printing to System.err [READ THIS!]
Posted by Jean-Noel Gadreau <jn...@activcard.com>.
+1 for 4 spaces. I think that is a usual convention in Java, with tab
equivalent to 8 spaces.
Jean-Noel
Ryo Neyama wrote:
>
> > Agreed on all counts, including the right way to do braces :), except I
> > personally really dislike 2-space indents; I think 4 spaces is a) more
> > standard in the Java world, and b) much more readable. As with brace style,
> > I'd say stick to a single style per file in any case.
> >
> > I wouldn't suggest changing the existing code that uses 2-space indents, but
> > I'd vote for 4 on all future code.
> >
> > --Glen
>
> I agree with Glen. Generally speaking(I know you must know), it's not
> good idea that there are too deep indentations in one method. When the
> indent becomes too deep, we should re-design the class and separate it
> into multiple methods by the functionality. In that sense, 4 spaces
> would be better than 2 spaces, because it can prevent the too deep
> indentations.
>
> BTW, the Linux kernel code convention recommends 8 spaces for that
> reason, although I think it's not good for us.
>
> Regards,
> Ryo Neyama @ IBM Research, Tokyo Research Laboratory
> Internet Technology
> neyama@trl.ibm.co.jp
Re: coding conventions and printing to System.err [READ THIS!]
Posted by Ryo Neyama <ne...@trl.ibm.co.jp>.
> Agreed on all counts, including the right way to do braces :), except I
> personally really dislike 2-space indents; I think 4 spaces is a) more
> standard in the Java world, and b) much more readable. As with brace style,
> I'd say stick to a single style per file in any case.
>
> I wouldn't suggest changing the existing code that uses 2-space indents, but
> I'd vote for 4 on all future code.
>
> --Glen
I agree with Glen. Generally speaking(I know you must know), it's not
good idea that there are too deep indentations in one method. When the
indent becomes too deep, we should re-design the class and separate it
into multiple methods by the functionality. In that sense, 4 spaces
would be better than 2 spaces, because it can prevent the too deep
indentations.
BTW, the Linux kernel code convention recommends 8 spaces for that
reason, although I think it's not good for us.
Regards,
Ryo Neyama @ IBM Research, Tokyo Research Laboratory
Internet Technology
neyama@trl.ibm.co.jp
Re: coding conventions and printing to System.err [READ THIS!]
Posted by Ryo Neyama <ne...@trl.ibm.co.jp>.
> Agreed on all counts, including the right way to do braces :), except I
> personally really dislike 2-space indents; I think 4 spaces is a) more
> standard in the Java world, and b) much more readable. As with brace style,
> I'd say stick to a single style per file in any case.
>
> I wouldn't suggest changing the existing code that uses 2-space indents, but
> I'd vote for 4 on all future code.
>
> --Glen
I agree with Glen. Generally speaking(I know you must know), it's not
good idea that there are too deep indentations in one method. When the
indent becomes too deep, we should re-design the class and separate it
into multiple methods by the functionality. In that sense, 4 spaces
would be better than 2 spaces, because it can prevent the too deep
indentations.
BTW, the Linux kernel code convention recommends 8 spaces for that
reason, although I think it's not good for us.
Regards,
Ryo Neyama @ IBM Research, Tokyo Research Laboratory
Internet Technology
neyama@trl.ibm.co.jp
Re: coding conventions and printing to System.err [READ THIS!]
Posted by Glen Daniels <gd...@allaire.com>.
Agreed on all counts, including the right way to do braces :), except I
personally really dislike 2-space indents; I think 4 spaces is a) more
standard in the Java world, and b) much more readable. As with brace style,
I'd say stick to a single style per file in any case.
I wouldn't suggest changing the existing code that uses 2-space indents, but
I'd vote for 4 on all future code.
--Glen
P.S. http://java.sun.com/docs/codeconv/html/CodeConventions.doc3.html#262
agrees! :)
----- Original Message -----
From: Sanjiva Weerawarana <sa...@watson.ibm.com>
To: <so...@xml.apache.org>
Sent: Wednesday, November 15, 2000 7:01 AM
Subject: Re: coding conventions and printing to System.err [READ THIS!]
> [ARGH, I pressed the wrong button too early. ARGH. Please ignore the
> previous message and read this!]
>
> I was just looking through some of the recently committed code and I
> see some problems that we as committers need to avoid now and not
> later. I know we're putting our effort on the 3.0 codebase, but as
> long as the other one is the live version we need to be careful about
> the code we commit.
>
> - handling exceptions by printing to stderr and returning null
> This just won't do on the server side .. the code must do proper
> error propagation or the whole thing becomes unusable.
> Can each person please check and correct their code if needed?
> (I'm assuming there's no disagreement on this topic!)
> If you do put print stmts to debug while developing, then please
> remove those before committing the code.
>
> - coding styles
> We each have our own coding style obviously. However, we're working
> on a shared repository, so IMO we need to follow a single convention
> as much as possible. I propose the following:
> - maintain the 80 characters per line rule: if its longer break the
> line
> - upper/lower casing of variables/method/classes: follow the standard
> Java conventions
> - indentation: I suggest we keep to 2 spaces per nesting level. In
> any case, no tabs. In any case, *please* indent .. don't put
> things on the same line because we can .. Java is free-form and
> using that free-form ends up in a more maintainable codebase.
> - placement of "{" and "}": my preferred convention is to put the
> "{" at the end of the previous thing:
> if (foo bar) {
> ...
> }
> and the "}" on a line by itself, except for if-then-else. This is
> most religious amongst people (Matt for example insists on doing it
> the wrong way) and as such I suggest that we keep to exactly one
> convention in a single file. That is, if I started editing the file
> then it'll be done as above (i.e., the right way :-)) and if Matt
> started it then it'll be done the wrong way. In either case, when
> someone adds new code it should follow the convention that's
established
> for that file. If someone is essentially taking over the entire
file,
> then that person can do it their way.
>
> - old code when new code is added
> When some new code is committed the old code should be removed, not
> commented out. If something goes wrong we always have the older
version
> to go back to, so there's no need to comment out and keep stuff.
>
> - comments
> We are a diverse group of people working on this code. As such,
> comments are an absolutely necessary part of the code! I suggest that
> everyone put a class-level comment telling what the class does etc.
> and puts as much inlined comments as possible documenting the code.
>
> I hope this doesn't come out the wrong way .. I'm not trying to "control"
> this codebase - we have a working, stable codebase and we're making
> incremental changes to it (a good thing). Keep it working and stable will
> (IMO) require following some degree of discipline ..
>
> Sanjiva.
>
>
Re: coding conventions and printing to System.err [READ THIS!]
Posted by Glen Daniels <gd...@allaire.com>.
Agreed on all counts, including the right way to do braces :), except I
personally really dislike 2-space indents; I think 4 spaces is a) more
standard in the Java world, and b) much more readable. As with brace style,
I'd say stick to a single style per file in any case.
I wouldn't suggest changing the existing code that uses 2-space indents, but
I'd vote for 4 on all future code.
--Glen
P.S. http://java.sun.com/docs/codeconv/html/CodeConventions.doc3.html#262
agrees! :)
----- Original Message -----
From: Sanjiva Weerawarana <sa...@watson.ibm.com>
To: <so...@xml.apache.org>
Sent: Wednesday, November 15, 2000 7:01 AM
Subject: Re: coding conventions and printing to System.err [READ THIS!]
> [ARGH, I pressed the wrong button too early. ARGH. Please ignore the
> previous message and read this!]
>
> I was just looking through some of the recently committed code and I
> see some problems that we as committers need to avoid now and not
> later. I know we're putting our effort on the 3.0 codebase, but as
> long as the other one is the live version we need to be careful about
> the code we commit.
>
> - handling exceptions by printing to stderr and returning null
> This just won't do on the server side .. the code must do proper
> error propagation or the whole thing becomes unusable.
> Can each person please check and correct their code if needed?
> (I'm assuming there's no disagreement on this topic!)
> If you do put print stmts to debug while developing, then please
> remove those before committing the code.
>
> - coding styles
> We each have our own coding style obviously. However, we're working
> on a shared repository, so IMO we need to follow a single convention
> as much as possible. I propose the following:
> - maintain the 80 characters per line rule: if its longer break the
> line
> - upper/lower casing of variables/method/classes: follow the standard
> Java conventions
> - indentation: I suggest we keep to 2 spaces per nesting level. In
> any case, no tabs. In any case, *please* indent .. don't put
> things on the same line because we can .. Java is free-form and
> using that free-form ends up in a more maintainable codebase.
> - placement of "{" and "}": my preferred convention is to put the
> "{" at the end of the previous thing:
> if (foo bar) {
> ...
> }
> and the "}" on a line by itself, except for if-then-else. This is
> most religious amongst people (Matt for example insists on doing it
> the wrong way) and as such I suggest that we keep to exactly one
> convention in a single file. That is, if I started editing the file
> then it'll be done as above (i.e., the right way :-)) and if Matt
> started it then it'll be done the wrong way. In either case, when
> someone adds new code it should follow the convention that's
established
> for that file. If someone is essentially taking over the entire
file,
> then that person can do it their way.
>
> - old code when new code is added
> When some new code is committed the old code should be removed, not
> commented out. If something goes wrong we always have the older
version
> to go back to, so there's no need to comment out and keep stuff.
>
> - comments
> We are a diverse group of people working on this code. As such,
> comments are an absolutely necessary part of the code! I suggest that
> everyone put a class-level comment telling what the class does etc.
> and puts as much inlined comments as possible documenting the code.
>
> I hope this doesn't come out the wrong way .. I'm not trying to "control"
> this codebase - we have a working, stable codebase and we're making
> incremental changes to it (a good thing). Keep it working and stable will
> (IMO) require following some degree of discipline ..
>
> Sanjiva.
>
>