Gerald Brose

gerald.brose@acm.org


            JacORB Coding Conventions
            =========================

JacORB uses the Apache Jakarta Coding Style, which is based on the Sun
coding conventions for Java. Please see
http://jakarta.apache.org/turbine/common/code-standards.html for
reference.

(Re-formatting):
===============

The astyle tool (http://astyle.sourceforge.net/) can be used to format
source code. Note, however, that astyle will not *remove* whitespace,
e.g., within brackets.

You can use the following lines as your .astylerc file:

--- begin .astylerc file ----

#
# .astylerc file for JacORB, meant to reflect Apache Java Coding
# conventions
#

# default parsing is of java files
mode=java

# brackets should be attached to pre-bracket lines
brackets=attach

# set 4 spaces per indent
indent=spaces=4

# indent switch blocks
indent-switches

# suffix of original files should be .orig
suffix=.orig

# Break brackets from their pre-block statements (i.e. ANSI C, C++ style)
brackets=break

# Insert space padding around operators only:
pad=oper

# Convert tabs to spaces.
convert-tabs

--- end .astylerc file ----


To use astyle from within Emacs, make sure astyle is in your
PATH. Then add the following to your .emacs file (found on
the 'Net):


(defvar astyle-command "astyle")

(defun astyle-region (start end)
   "Run astyle on region, formatting it in a pleasant way."
   (interactive "r")
   (save-excursion
     (shell-command-on-region start end astyle-command nil t)
     (indent-region start end nil)))

(defun astyle-buffer ()
   "Run astyle on whole buffer, formatting it in a pleasant way."
   (interactive)
   (save-excursion
     (astyle-region (point-min) (point-max))))

(add-hook 'c-mode-common-hook
             '(lambda ()
                (define-key c-mode-map "\C-cr"  'astyle-region)
                (define-key c-mode-map "\C-cb"  'astyle-buffer)
                (define-key c++-mode-map "\C-cr"  'astyle-region)
                (define-key c++-mode-map "\C-cb"  'astyle-buffer)
                (define-key jde-mode-map "\C-cr"  'astyle-region)
                (define-key jde-mode-map "\C-cb"  'astyle-buffer)))



General rules
=============


1) Use whitespace to make the text more readable.

    a) indentation: 4 spaces, no tabs!

    b) Open curly brackets on a *new* line without further indentation

       if (x)
       {
       }

    c) always write the body of an if-, for-, while- ... statmement
       on a new line, never on the same!

       for (;;)
       {
           ...
       }

    d) write: x = y, not: x=y

    e) Include extra spaces around operators,
       For example:

             a = b * c

    f) No spaces between method names and opening brackets, e.g:

             a.method(arg1);

             public int myMethod(int param 1, ...)

    g) break lines that get too long  (around column 100)

    h) insert empty lines freely wherever you think it helps.


2) Comments:
    - as much as you can:
         javadoc public and package local methods and fields!!!
         javadoc private and protected ones also
    - add javadoc wherever you modify code (and you know what you are
      doing ;-) )

3) Place the JacORB LGPL license header on all files.

4) Tests
   a) When fixing a bug reference the bug number in the CVS commit.
   b) Either add to an existing test or add to the
      org.jacorb.test.bugs.bugXXX structure.
   c) Reference the test and code in the bugzilla entry.
   d) Ensure the test is javadoced including the reason for the
      test.
   e) When modifying code in the main tree, if there is missing javadoc
      in the function you are changing fix that as well.


[ More suggestions? ... ]