Re: Coding conventions

[Thomas Fischer <tf...@apache.org>]

Hi,

Let me first try to explain the problem which I have:

At the moment, we do not have a clearly defined code style at the moment. 
So the db guidelines say that we have to use SUNs coding conventions. But 
these standards are NOT used by anybody commiting Torque code at the 
moment, nor does our existing code comply: Two things that strike me 
instantly is that SUN promotes an indent of 8 spaces, while we use four. 
Also, SUN promotes that opening curly braces should be at the end of the 
line, while we use an extra line.

Now I wanted to put a document somewhere where our current style is laid 
down, so 1) we comply to the db project guidelines, and 2) new developers 
or people submitting a patch can read it. And becaue we already use the 
turbine style, I did not think that a discussion was necessary, but I was 
wrong, obviously. (I should have learnt that by now. Never start talking 
about coding conventions. NEVER !)

Perhaps I did not make this clear, but I do NOT AT ALL propose to reformat 
any existing code. I am talking about new code.

I also did not check the emacs styles in the tubine style sheet, I was 
going by the human-readable part. By the way, I do not think there are 
many people using emacs now that eclipse is around, but I might also be 
wrong there.

I would also heartily agree with your final advice, but I do think we 
should say something about the preferences we have. And from what I 
have seen, people writing code for Torque prefer 4 spaces indent over 8 
spaces indent (and abhor tabs), and like to have their opening curly 
braces in new lines.

      Thomas

On Sat, 27 Aug 2005, Henning P. Schmiedehausen wrote:

> Thomas Fischer <tf...@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
>
>

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