--  CODING GUIDELINES for the PolyORB project

--  $Id$

First read the file CONTRIBUTING for legal instructions for
contributors.

The Ada 95 Quality & Style Guide is included by reference.

Code layout should follow the usual GNAT practice.

Every package that can be declared Pure shall, then:
every package that can be Preelaborate shall, then:
every package that can have an Elaborate_Body pragma shall, then:
every package that cannot or need not have any of the above shall
have a comment that explains why.

Each file should start with the standard PolyORB copyright header,
then a blank line, then a comment that documents its purpose, followed
by a blank line. The PolyORB copyright header might be adapted for
copyrighted specs or code from third party.

If a package body needs to explicitly execute some code for its
initialization, this MUST NOT be done in the elaboration code.
Instead, a parameterless procedure Initialize must be declared
containing the necessary initialization code, and this procedure
should be registered with the initialization procedure,
PolyORB.Initialization.

Direct use of tasking runtime or any constructs that would drag tasking in
its dependencies is explicitly prohibited. All concurrent programming is
to be performed using PolyORB.Tasking.* API. This also applies to C code,
which may not call the pthreads library directly.

No dependencies on personality specific code are allowed anywhere except in
units implementing this specific personality.

All the code shall be compilable with pragma Profile (Ravenscar), except for
code dedicated to very specific functions such as concurrent constructions.
This should be clearly indicated in package name and source code.

The code shall not produce warnings when compiled with -gnatwa -gnaty.
Any use of pragma Warnings (Off) shall be documented by a comment.

Usage of Ada 2005 features is restricted as follows:

  * in the IDL to Ada compilers, the following Ada 2005 features are allowed:

     - raise .. with "";
     - object.method notation
     - limited with
     - anonymous access fields/parameters
     - use of overriding keyword.

    All other Ada 2005 features are prohibited.

  * elsewhere in PolyORB, Ada 2005 specific features are prohibited; the
    code must be legal in both Ada 95 and Ada 2005.

  * in addition to the restrictions below, there is a general requirement
    that PolyORB can be compiled with any GNAT version that is listed as
    supported in the PolyORB User's Guide.

When necessary, tag the code with

- 'XXX' to indicate dubious code.

- 'WAG:Y.ZZ' to indicate constructions used to work around a behavior
  in GNAT version Y.ZZ.

- 'Implementation note:' to indicate modifications to a 'should be'
  implementation to work around specific problems.

Whenever possible, do not add new exceptions and exception handlers to
PolyORB's neutral core and protocol personalities. Instead, use error
handling mechanisms provided by PolyORB.Exceptions.

Header box should be up to date whenever necessary:

- Copyright date information is either 
  - x where x is year of code's creation,
  - y - z where y is year of code's creation and z is year of last
    modification, if y /= z.

By code's creation, we mean the date the code was first created and
checked in in PolyORB repository. If packages are renamed, merged,
copyright years must remain consistent with package content.

- Some packages require specific adjustments to take into account
  references to specifications (e.g. CORBA related packages) or other
  projects (e.g. AWS)

Always update the MANIFEST file and any makefile.am when the source
tree is modified.

Always update (or create if necessary) README file for each example.

New features and incompatible changes shall be documented in the
section of the NEWS file pertaining to the upcoming release. Any
change in name or semantics of a configuration variable must be
considered an incompatible change. Any new configuration variable must
be documented as a new feature. 

Any modification to NEWS must be propagated to the PolyORB User's
guide to ensure consistency.

Recompute build dependencies every time the semantic dependencies
of a unit are modified.

To do so, run 'make depend' from PolyORB's root directory.
Note that you must ensure that:

- Build is made _without_ debug

- Source tree and build tree are equal