PolyORB/doc/CODING_GUIDELINES

--  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 -gnatyg.
Any use of pragma Warnings (Off) shall be documented by a comment.

Usage of post-Ada 95 features is restricted as follows:

  * The following Ada 2005 features are allowed:

     - use of Ada.Directories
     - use of Ada.Containers and children thereof
     - raise EXC with STR
     - Object.Method notation
     - anonymous access components and objects
     - use of "overriding" and "not overriding" indicators
     - abstract interfaces

  * No Ada 2012 feature is permitted.

  * All other post-Ada 95 features are prohibited. In particular, the code must
    be compatible with application components using Ada 95, Ada 2005, or
    Ada 2012. Any unit containing a post-Ada 95 construct must have a pragma
    Ada_2012. (Note that pragma Ada 2005 cannot be used, as it is no longer
    supported by GNAT Community releases).

  * In addition to the restrictions above, 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 constructs used to work around a behavior
  in GNAT version Y.ZZ (the intent of these markers is to allow such
  work-arounds to be removed once version Y.ZZ is not listed anymore
  as supported for building PolyORB).

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

Whenever possible, do not add new exceptions or 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
features-XXX file pertaining to the upcoming release. These files
document what *new* features are present in a given release. A valid
tracking number must be included for every new feature. 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, and also added to the example
src/polyorb.conf file.

Major new features must also be included in the FEATURES file, which
gives an overview of what PolyORB provides.

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