mirror of
https://github.com/AdaCore/PolyORB.git
synced 2026-02-12 13:01:15 -08:00
709bc4f2a7
Update coding guidelines to mention these files. Clean up release procedure. For G118-014. Subversion-branch: /trunk/polyorb Subversion-revision: 42017
122 lines
4.6 KiB
Plaintext
122 lines
4.6 KiB
Plaintext
-- 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
|
|
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.
|
|
|
|
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
|