...
Coding
...
standards
...
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
...
...
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 
Headers
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
...
:
| Code Block |
|---|
} /* * 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. * */ {code} h3. Class |
Class/Interface
...
headers
...
Each
...
Class
...
or
...
Interface
...
should
...
have
...
an
...
header
...
which
...
must
...
contains
...
:
...
- A
...
- descrption
...
- of
...
- this
...
- class/interface
...
- an
...
- author
...
- tag
...
- which
...
- should
...
- be
...
- :
...
Code Block
...
@author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
...
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...)
...
If
...
- you
...
- use
...
- html
...
- tags,
...
- remember
...
- to
...
- escape
...
- '<'
...
- and
...
- '>'
...
- characters...
...
Static
...
members
...
and
...
other
...
members
...
Just
...
add
...
a
...
sinle
...
line
...
javadoc
...
comment
...
like
...
:
...
/*
...
blah
...
...
...
*/
...
*
...
before
...
each
...
member
...
Methods
Follow the standard javadoc rules : Description, @param, @exception and @return. It should be enough. No @tags, @todo tags, etc...
Escape html characters
Comments
No special rules, except that you should avoid :
- Useless comments like : i++; /* Increment i */
- Overusing comments : if you have to heavily comment a peice of code, then this piece of code might be too complex ...
- Speading little comments all over a method : if possible, write blocs of comments. The method header could hgenerally contains a full description of the code, and if it's not the case, just consider your method might be too long !
- Dead code commented. If it's dead, then put it in a cuffin. We use SVN, the Ressuscitator !
Basically, use your common sense 
Naming
Naming ! Sounds like Blaming . Ok. We use Sun(tm/c/r)
...
style
...
:
...
- Constants
...
- are
...
- in
...
- UPPER
...
- CASE
...
- with
...
- accepted
...
- '_'
...
- Class
...
- starts
...
- with
...
- an
...
- uppercase
...
- and
...
- each
...
- starting
...
- word
...
- is
...
- upper
...
- cased.
...
- No
...
- '_',
...
- please
...
- !
...
- Methods
...
- starts
...
- with
...
- lower
...
- case
...
- and
...
- then
...
- follow
...
- the
...
- same
...
- rule
...
- than
...
- classes.
...
- No
...
- '_',
...
- please
...
- !
...
- Interfaces
...
- should
...
- not
...
- start
...
- with
...
- an
...
- 'I'
...
- Classes
...
- which
...
- implements
...
- an
...
- Interface
...
- must
...
- be
...
- followed
...
- by
...
- the
...
- postfix
...
- 'impl'
...
- Variables
...
- follow
...
- the
...
- method
...
- naming
...
- convention.
...
- No
...
- '_',
...
- please
...
- !
...
- Use
...
- meaningfull
...
- names.
...
- No
...
- double
...
- letter
...
- variables
...
- like
...
- ii,
...
- jj
...
- etc...
...
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.
Spaces vs tabs
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.
Formatting
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 :
- Always use '{' and '}' even for a single instruction, or if you have an empty block (don't use ';' for empty blocks)
- No more than one instruction on a single line, the only exception is the '?' ':' operation
- Use this to address the class variable if there is a risk of confusion (for instanc eif you have a parameter with the same name.
- Don't add a 'a_', or 'the_' before a parameter's name to distinguish it from the class variable which has the same name. Use this instead.
- Don't add final everywhere. Even if final is a substitute for const, it's semantic is not clear enough that you use it everywhere.
Imports
Always declare all the classes you import, do not use x.y.*
What else ?
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
Ldap RFCs
Here is a list of all LDAP related RFCs (grey and maekred (obs are obsoleted RFCs :
RFC 1274 (obs) : The COSINE and Internet X.500 Schema.
RFC 1485 (obs) : A String Representation of Distinguished Names (OSI-DS 23 (v5)).
RFC 1487 : X.500 Lightweight Directory Access Protocol
RFC 1558 (obs) : A String Representation of LDAP Search Filters.
RFC 1777: Lightweight Directory Access Protocol.
RFC 1779 (obs) : A String Representation of Distinguished Names.
RFC 1823: The LDAP Application Program Interface.
RFC 1959 (obs) : An LDAP URL Format.
RFC 1960 (obs) : A String Representation of LDAP Search Filters.
RFC 2164: Use of an X.500/LDAP directory to support MIXER address mapping.
RFC 2247: Using Domains in LDAP/X.500 Distinguished Names.
RFC 2251 (obs) : Lightweight Directory Access Protocol (v3).
RFC 2252 (obs) : Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions.
RFC 2253 (obs) : Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names.
RFC 2254 (obs) : The String Representation of LDAP Search Filters.
RFC 2255 (obs) : The LDAP URL Format.
RFC 2256 (obs) : A Summary of the X.500(96) User Schema for use with LDAPv3.
RFC 2307: An Approach for Using LDAP as a Network Information Service.
RFC 2559: Internet X.509 Public Key Infrastructure Operational Protocols - LDAPv2.
RFC 2587 (obs) : Internet X.509 Public Key Infrastructure LDAPv2 Schema.
RFC 2596 (obs) : Use of Language Codes in LDAP
RFC 2649: An LDAP Control and Schema for Holding Operation Signatures.
RFC 2696: LDAP Control Extension for Simple Paged Results Manipulation.
RFC 2798: Definition of the inetOrgPerson LDAP Object Class.
RFC 2820: Access Control Requirements for LDAP
RFC 2829 (obs) : Authentication Methods for LDAP
RFC 2830 (obs) : Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security.
RFC 2849: The LDAP Data Interchange Format (LDIF) - Technical Specification.
RFC 2926: Conversion of LDAP Schemas to and from SLP Templates.
RFC 3045: Storing Vendor Information in the LDAP root
RFC 3062: LDAP Password Modify Extended Operation.
RFC 3088: OpenLDAP Root Service An experimental LDAP referral service.
RFC 3112: LDAP Authentication Password Schema.
RFC 3296: Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories.
RFC 3377 (obs) : Lightweight Directory Access Protocol (v3): Technical Specification.
RFC 3383 (obs) : Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP).
RFC 3384: Lightweight Directory Access Protocol (version 3) Replication Requirements.
RFC 3663: Domain Administrative Data in Lightweight Directory Access Protocol (LDAP).
RFC 3671: Collective Attributes in the Lightweight Directory Access Protocol (LDAP).
RFC 3672: Subentries in the Lightweight Directory Access Protocol (LDAP).
RFC 3674 (obs) : Feature Discovery in Lightweight Directory Access Protocol (LDAP).
RFC 3698: Lightweight Directory Access Protocol (LDAP): Additional Matching Rules.
RFC 3703: Policy Core Lightweight Directory Access Protocol (LDAP) Schema.
RFC 3712: Lightweight Directory Access Protocol (LDAP): Schema for Printer Services.
RFC 3771 (obs) : The Lightweight Directory Access Protocol (LDAP) Intermediate Response Message.
RFC 3866: Language Tags and Ranges in the Lightweight Directory Access Protocol (LDAP).
RFC 3909: Lightweight Directory Access Protocol (LDAP) Cancel Operation.
RFC 3928: Lightweight Directory Access Protocol (LDAP) Client Update Protocol (LCUP).
RFC 4104: Policy Core Extension Lightweight Directory Access Protocol Schema (PCELS).
RFC 4373: Lightweight Directory Access Protocol (LDAP) Bulk Update/Replication Protocol (LBURP).
RFC 4403: Lightweight Directory Access Protocol (LDAP) Schema for Universal Description, Discovery, and Integration version 3 (UDDIv3).
RFC 4510: Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map.
RFC 4511: Lightweight Directory Access Protocol (LDAP): The Protocol.
RFC 4512: Lightweight Directory Access Protocol (LDAP): Directory Information Models.
RFC 4513: Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms.
RFC 4514: Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names.
RFC 4515: Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters.
RFC 4516: Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator.
RFC 4517: Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules.
RFC 4518: Lightweight Directory Access Protocol (LDAP): Internationalized String Preparation.
RFC 4519: Lightweight Directory Access Protocol (LDAP): Schema for User Applications.
RFC 4520: Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP).
RFC 4521: Considerations for Lightweight Directory Access Protocol (LDAP) Extensions.
RFC 4522: Lightweight Directory Access Protocol (LDAP): The Binary Encoding Option.
RFC 4523: Lightweight Directory Access Protocol (LDAP) Schema Definitions for X.509 Certificates.
RFC 4524: COSINE LDAP/X.500 Schema.
RFC 4525: Lightweight Directory Access Protocol (LDAP) Modify-Increment Extension.
RFC 4526: Lightweight Directory Access Protocol (LDAP) Absolute True and False Filters.
RFC 4527: Lightweight Directory Access Protocol (LDAP) Read Entry Controls.
RFC 4528: Lightweight Directory Access Protocol (LDAP) Assertion Control.
RFC 4529: Requesting Attributes by Object Class in the Lightweight Directory Access Protocol.
RFC 4530: Lightweight Directory Access Protocol (LDAP) entryUUID Operational Attribute.
RFC 4531: Lightweight Directory Access Protocol (LDAP) Turn Operation.
RFC 4532: Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation.
RFC 4533: The Lightweight Directory Access Protocol (LDAP) Content Synchronization Operation.
Here is a list of drafts :
I-Ds List Working Group, LDAP Extension (ldapext)
(If you need help you can subscribe and ask your questions to the developers mailing list)