Welcome to you, developper ! You have been elected committer on the project, or you want to contribute some code or some patch? This is great news. However, in order to be able to share your 'vision' and your code, some rules must be followed.
Hey, remember that those rules are not the best nor the worst, they are pretty much what they are for historical reasons, or for technical reasons, however, please, accept them as they are, and avoid religious war (please, oh please, no mail to say "WTF ? You are using spaces instead of tab ??? How stupid is this rule etc etc.) Rules are always stupid, but smart people follow them
Eclipse users can import those two files to enfore the code formating : formatting.xml and codetemplates.xml |
IDEA users can import this file to enfore the code formating : settings.jar |
First, you must (and this rule accept no exception) use this header in top of all source file, or each file in which you can have comments :
/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. * */ |
Each Class or Interface should have an header which must contains :
@author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> |
If you use html tags, remember to escape '<' and '>' characters...Thanks to avoid to put your name. The code is not yours, and much more important, but putting ypur name and e-mail, you will intimidate other developper ("Oh, no, I won't mess with this code, it has been developped by XXXX !") and second, you will receive mail in three years even if you have stopped all commitment on the project (and those who have sent you an e-mail will think that the project's memeber are not responsive...)
Just add a sinle line javadoc comment like : /* blah ... */* before each member
Follow the standard javadoc rules : Description, @param, @exception and @return. It should be enough. No @tags, @todo tags, etc...
Escape html characters
No special rules, except that you should avoid :
Basically, use your common sense
Naming ! Sounds like Blaming . Ok. We use Sun(tm/c/r) style :
If you browse the code, you will see that many classes does not respect those rules. That's life ! Don't fix it if you don't touch a class. If you are fixing a method in a class, then you can change the code to respect the rules. Little by little, we may reach a stable state where all the code respect the rules
Naming is really important for APIs. Be smart. If you are not sure, ask.
FOUR SPACES, NO TAB. Final.
No discussion. Using tabs break diffs. Modify your IDE to insert spaces when you use tabs, before it saves the file.
Use the formatting.xml file which can be found in the resources directory in the root of the project. This is for Eclipse. If you don't use eclipse, then translate the formating to your favorite IDE
Use the codetemplates.xml file if you are using Eclipse too. You will find it at the same location. It brings you some standard headers for new classes, nex methods, etc.
Use UTF-8 as a default for your files (except for properties, thanks to java, which should be in ISO-8859-1). Forget about exotic encoding...
*DO NOT USE AN AUTOMATIC FORMATER FOR COMMENTS !!!* People spend a lot of time making their comment looks like pretty, so if you just format them, you will have to recover the previous comments...
Some general rules :
This is a code example :
... int result = myMethod( param1, param2 ) if ( result > 0 ) { // do something } ... |
Always declare all the classes you import, do not use x.y.*
Well, this was a very short introduction about coding rules. Use commen sense, look at what you see around you when adding some code, ask people about format, if you have a question.
That's it ! (I wait your comments, guys