db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Henning P. Schmiedehausen" <...@intermeta.de>
Subject Re: [VOTE] Coding conventions
Date Sat, 27 Aug 2005 11:02:09 GMT
Thomas Fischer <tfischer@apache.org> writes:

Hm. Actually, I don't really understand this vote. We should've had
some discussion first.  :-)

First my vote:

>[X] +1 Torque code should be written according to the Turbine code
>          conventions.

The problem is, that the "Turbine Coding standard" are at best a
loosely defined collection of do's and don't's (at
http://jakarta.apache.org/turbine/common/code-standards.html) with a
(broken) checkstyle definition in maven-checkstyle-plugin.

It is (IMHO) just a document that describes how some (one?) of the
original Turbine people write code. It has a number of glaring
ambiguities (like the if (foo) and if ( foo ) ) convention.

The attached .emacs file makes it even worse. If you reformat a buffer
with this style, the result will not confirm to the style
described. :-) Also, it is almost impossible to configure Jalopy to
format code just like this emacs style. And eclipse again formats
different.

However, I strongly advise _against_ reformatting the source code into
another format. Not because I'm clinging to the current style. But
because I've learned (the hard way), that reformatting source code is
almost always a bad idea. This like indenting (4 spaces? 8 spaces?
tabs?), brace positions and everything else are a matter of personal
taste. Every developer does it differently. And having two developers
using a different coding style working on the same file will let real
changes drown in a sea of "indent and brace position changes".

Having a coding style is better than having none. But changing a code
style is even worse than having no coding style.

What I would _love_ to have (even some people will cry out in horror)
is a subversion pre-commit hook on the server, which takes .java files
and reformats them to a coding style set on the server. And reject a
checkin if a file has only formatting changes unless they still exist
after reformatting.

This would make sure, that only correctly formatted code will hit the
repository. And it would allow developers to cling to their own style
and first thing after a checkout is to reformat the project according
to their personal tastes.

If you really care about code style, then you should take a peek at
the following things (IMHO):

- Code Conventions for the Java(TM) Programming Language.
   http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
   This is a surprisingly stable document (last revision is from '99)
   describing how to format code.

   I have some problems with it (Tabs vs. Spaces is one) but it is
   a good guide how a style guide _can_ look like and it is a great
   foundation to build upon.

- "The Elements of Java Style" -- ISBN 0-521-77768-2
   If you don't own this booklet, try to steal it somewhere. If you
   want to write professional Java code and don't know this book, you
   did something wrong. 

   I hate their control statement indentation (I do believe, BSD style is
   more readable), but that is personal. They hate hard tabs too, which is
   good. 

- The output of checkstyle, pmd and findbugs. 
   As we are using a maven build, we get all three of them for free. While
   (especially Findbugs) sometimes point to false warnings, most of the 
   time the damned tools are right (The current Torque code still contains about
   fifteen 'tab' characters in the runtime alone).

My final advice is to apply some reason. Is it really necessary to
reformat a file you're working on? The LKM people basically say "if
you work on foo.c, try to keep the indentation as closely as possible
to the original style of the code. If it's K&R, keep K&R, if it's BSD,
keep BSD".

	Regards
		Henning

-- 
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen          INTERMETA GmbH
hps@intermeta.de        +49 9131 50 654 0   http://www.intermeta.de/

RedHat Certified Engineer -- Jakarta Turbine Development  -- hero for hire
   Linux, Java, perl, Solaris -- Consulting, Training, Development

		      4 - 8 - 15 - 16 - 23 - 42

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


Mime
View raw message