You are viewing a plain text version of this content. The canonical link for it is here.
Posted to j-dev@xerces.apache.org by Rajiv Mordani <Ra...@eng.sun.com> on 2000/04/14 05:46:08 UTC
Coding conventions.
Can we to start with follow the java coding conventions put out at
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
Actually the most important thing I think is that code shouldn't go beyond
80 columns. If that happens break the line at 80. It makes code readable
in terminals. Otherwise it becomes difficult to follow it sometimes.
- Rajiv
--
:wq
RE: Coding conventions.
Posted by Dwayne Schultz <Dw...@Schultz.net>.
What sorta worked on one project (I'm obviously not a salesman) was the tech
writers were allowed to do more reformatting while developers shouldn't.
When looking back through diffs, if you saw a revision checked in from the
tech writer, you knew it was only documentation changes. We still ended up
looking at a mess if we had to diff code that was several revs apart.
I don't know if there are tech writers on this project but I thought I would
throw that out there.
Re: Coding conventions.
Posted by Mike Pogue <mp...@apache.org>.
I agree with the "if you touch it, make it nicer" thought here.
However, what I want to avoid is the "if you touch it, make minor changes
to indenting style, use of braces, etc." idea.
Too often, people make changes like this:
if (foo==bar) {
stuff...
}
changes to
if (foo == bar)
{
stuff...
}
which causes lots of extra lines in the diff, with no real benefit in readability or
maintainability.
Then, the next person who touches the file changes it back to the original way,
which creates even more extra lines in the diff.
I've been in too many "my style is the right style" discussions, to believe that
this will be easily resolved.
Mike
Andy Clark wrote:
>
> David Bourget wrote:
> > I think narrow code conventions are, like Mike said, a waste of time in a
> > project like Xerces, but some very basic guidelines should be followed to
> > ensure readability.
>
> I agree, to an extent. Everyone has their own coding style but
> following some basics will help understanding. We should scour
> the code and "clean" it up with more whitespace, comments, and
> adding javadoc comments to *every* class, interface, method,
> and field. This is not an easy task but it will be worth it!
>
> I propose that, at the very minimum, that when someone touches
> a source file, that they fill in missing comments and javadoc
> of the methods, etc that they work on. In this way, over time
> we'll have covered the entire code base. Whatcha think?
>
> --
> Andy Clark * IBM, JTC - Silicon Valley * andyc@apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
> For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
Re: Coding conventions.
Posted by Andy Clark <an...@apache.org>.
David Bourget wrote:
> I think narrow code conventions are, like Mike said, a waste of time in a
> project like Xerces, but some very basic guidelines should be followed to
> ensure readability.
I agree, to an extent. Everyone has their own coding style but
following some basics will help understanding. We should scour
the code and "clean" it up with more whitespace, comments, and
adding javadoc comments to *every* class, interface, method,
and field. This is not an easy task but it will be worth it!
I propose that, at the very minimum, that when someone touches
a source file, that they fill in missing comments and javadoc
of the methods, etc that they work on. In this way, over time
we'll have covered the entire code base. Whatcha think?
--
Andy Clark * IBM, JTC - Silicon Valley * andyc@apache.org
Re: Coding conventions.
Posted by David Bourget <ro...@dbourget.com>.
Hi all,
As a newcomer to the Xerces world I already have an opinion on this topic.
I must admit that the lack of good taste in some parts of the actual source
rebuted me slightly. Well, the style does not makes the runtime bytes, but
it does help you relax your eyes and concentrate on the actual meaning of
the code instead of assembling the visual puzzle.
I think narrow code conventions are, like Mike said, a waste of time in a
project like Xerces, but some very basic guidelines should be followed to
ensure readability.
What really annoyed me is the lack of spaces between function definitions ,
blocks etc in some parts of the code. I can't see why one would not want to
white lines when this makes the thing alot easier to read, thus saving you
time. Maybe this is the work of an IDE.
I hope I have not hurted anyone, this is just an opinion,
David
> I would think otherwise. There should be some consistency in the style of
> the code that is being written, and since there are so many of us the only
> way to get the consistency is by some coding conventions. For a start, I
> pointed to the java coding conventions used here at Sun. Also almost every
> other project under Apache has one, so why not have one for xml.apache
> too??
Re: Coding conventions.
Posted by Rajiv Mordani <Ra...@eng.sun.com>.
I would think otherwise. There should be some consistency in the style of
the code that is being written, and since there are so many of us the only
way to get the consistency is by some coding conventions. For a start, I
pointed to the java coding conventions used here at Sun. Also almost every
other project under Apache has one, so why not have one for xml.apache
too??
When the world has the code to look at, I think it is important to have
code which is presentable. People shouldn't have to think twice before
starting to look at the code cos it doesn't fit in their editor ;)...
I would like to propose just the following 2 things for a start -
1. Do NOT go beyond 80 columns. Even if I use an advanced editor I don't
want to end up scrolling.
2. For comments exceeding one line use /* */ rather than '//' on each line
of the comment.
However over time I would expect a whole set of coding conventions to be
followed in xml.apache as is being done in the other Apache projects - be
it one that is created here or just use the one on java.sun.com.
The benifit of having coding conventions is that people other than the
original author can also look at it and understand it, and incase the
original author no longer works for the company / team there are other
people who can take up that piece of code for maintenance / further
development..
So once again I would encourage developers to USE coding conventions.
- Rajiv
--
:wq
On Fri, 14 Apr 2000, Mike Pogue wrote:
> I vote -1 on coding conventions. I have had WAY too many discussions about
> them in the past to believe that we will be able to converge, or that they
> have any real benefit. Sorry! (If your editor only has 80 columns,
> you should buy yourself an editor written sometime after the 70's! :-)
>
> Mike's List of Infinite Time Sinks
> ----------------------------------
> coding conventions (including the ever-popular tabs vs spaces discussion,
> proper placement of "{", etc.)
> version numbering (three dots or four? what do they Really Mean?)
> editors (includes the famous emacs vs. vi wars)
> NL vs LF (OK, this one is specific to OS/390, but it still wastes an
> infinite amount of time if you touch it)
> Mac vs PC (Just say no!)
>
> :-)
> Mike
>
> Rajiv Mordani wrote:
> >
> > Can we to start with follow the java coding conventions put out at
> >
> > http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
> >
> > Actually the most important thing I think is that code shouldn't go beyond
> > 80 columns. If that happens break the line at 80. It makes code readable
> > in terminals. Otherwise it becomes difficult to follow it sometimes.
> >
> > - Rajiv
> >
> > --
> > :wq
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
> > For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
> For additional commands, e-mail: xerces-j-dev-help@xml.apache.org
>
Re: Coding conventions.
Posted by Mike Pogue <mp...@apache.org>.
I vote -1 on coding conventions. I have had WAY too many discussions about
them in the past to believe that we will be able to converge, or that they
have any real benefit. Sorry! (If your editor only has 80 columns,
you should buy yourself an editor written sometime after the 70's! :-)
Mike's List of Infinite Time Sinks
----------------------------------
coding conventions (including the ever-popular tabs vs spaces discussion,
proper placement of "{", etc.)
version numbering (three dots or four? what do they Really Mean?)
editors (includes the famous emacs vs. vi wars)
NL vs LF (OK, this one is specific to OS/390, but it still wastes an
infinite amount of time if you touch it)
Mac vs PC (Just say no!)
:-)
Mike
Rajiv Mordani wrote:
>
> Can we to start with follow the java coding conventions put out at
>
> http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
>
> Actually the most important thing I think is that code shouldn't go beyond
> 80 columns. If that happens break the line at 80. It makes code readable
> in terminals. Otherwise it becomes difficult to follow it sometimes.
>
> - Rajiv
>
> --
> :wq
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: xerces-j-dev-unsubscribe@xml.apache.org
> For additional commands, e-mail: xerces-j-dev-help@xml.apache.org