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

JacORB uses a similar style to Apache CommonsNet Coding Style, which is based on the Oracle
coding conventions for Java. Please see
https://commons.apache.org/proper/commons-net/code-standards.html.

A reference Eclipse coding standard is provided here https://gist.github.com/rnc/1fa85360300a2d78c087

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 120)

    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 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.
