ApCoCoALib:CodingGuidelines

This document handles some guidelines for the development of packages for ApCoCoA. If you are looking for hints regarding ApCoCoALib please consider ApCoCoA:CodingGuidelines.

General Rules

Please follow the CoCoALib coding guidlines unless noted otherwise. A part of these rules can be found here.

capitalization

There is one difference with respect to CoCoA's capitalization rule: Every letter at the beginning of a new word should be capital.

So it is still "PolynomialRing", but "Ring" where CoCoA would call it a "ring". We think this rule simplifies the naming process. This rule applies to class names as well as file names.

GPL notice

Please use the following GPL notice for all your source files:

//
// This file is part of the source of ApCoCoALib, the ApCoCoA Library.
//
//   Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)
//
//   Author[s]: YEAR[S], NAME[S] OF AUTHOR[S]
//
// Visit http://apcocoa.org/ for more information regarding ApCoCoA
// and ApCoCoALib.
// Visit http://www.apcocoa.org/wiki/ApCoCoA:KnownIssues for bugs, problems 
// and known issues.
//
// ApCoCoALib is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License (version 2 or later)
// as published by the Free Software Foundation. A copy of the full
// licence may be found in the file COPYING in this directory.
//
// ApCoCoALib is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with ApCoCoALib; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Please use the following GPL notice for all your documentation files:

Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)

Author[s]: YEAR[S] NAME[S] OF AUTHOR[S]

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the file COPYING in this directory.

Namespace issues

Do not use "using" to automatically embed namespaces, including std or CoCoA. Include your code into the following namespace structure:

namespace ApCoCoA{
 namespace AlgebraicCore{}
 namespace NumericalCore{}
 namespace AlgebraicAlgorithms{}
 namespace NumericalAlgorithms{}
}

Still, use ApCoCoA::*; and use CoCoA; may not produce any conflicts, so please name your classes, enums and functions correspondingly.

For bigger sets of functions, e.g. to implement one more complex algorithm, using help classes, typedefs etc. create a corresponding sub namespace. e.g.

namespace ApCoCoA{
 namespace NumericAlgorithms{
   void GBasisOfPoints(); // the function/ a wrapper starting the algorithm.
   namespace ABM{
     // functions / classes / typedefs for the algorithm.
   }
 }
}

Thereby, there must be a function in ApCoCoA::NumericalAlgorithms, calling the implemented algorithm. The names in the subnamespace may, but should not produce conflicts, if they are used together with the other, above mentioned namespaces.

Directory Structure

the include directory

include/
    ./Algebraical/
      ./Internal/
    ./Numerical/
      ./Internal/
Library.h
NumericalLibrary.h
AlgebraicalLibrary.h

the include directory contains three headers, AlgebraicalLibrary.H, including all top-level headers, offering algebraical methods, the NumericalLibrary.H including all top-level methods which are not purely algebraical. So hybrid methods should be also in numerical. Library.H includes all top-level methods.

The files, numerical_library.h is referring to must be in include/numerical. the files of algebraic_library.h therefore in include/algebraical. Header files defining internal structures, which are not top-level methods (e.g. help functions and classes, internal typedefs and so on) should be in a corresponding "internal" sub-directory. E.g. the matrix class for ABM, ABM::DoubleDenseMatrix, is in the subdirectory ApCoCoA/numerical/internal/. A rule of thumb: the directory structure is very close to the namespace, excluding a distinction between core and algorithms!

the source directory

Analogous to the header organisation, the source is split into numerical and algebraical. The files containing pure algebraic code should be in algebraical, everything else in numerical. Code which is grouped in a sub-namespace (e.g. ABM) should be in a corresponding directory. The .C-file containing the main functions (see namespace issues) which are not in the corresponding sub-namespace should also be in the subdirectory (e.g. ABM.H is in ApCoCoA/numerical/ but ABM.C is in ApCoCoA/numerical/ABM/ ). A rule of thumb: the directory structure is very close to the namespace, excluding the distinction between core and algorithms!

This article is a stub. You can make this wiki more useful by adding information.