Difference between revisions of "ApCoCoALib:CodingGuidelines"

From ApCoCoAWiki
m (Changed "ApCoCoA" to "ApCoCoALib" in the licence text)
(adding a link to ApCoCoA:CodingGuidelines)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
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==
 
==General Rules==
 
Please follow the CoCoALib coding guidlines unless noted otherwise.
 
Please follow the CoCoALib coding guidlines unless noted otherwise.
Line 10: Line 14:
 
==GPL notice==
 
==GPL notice==
  
Please use the following GPL notice for all your files:
+
Please use the following GPL notice for all your source files:
 
  //
 
  //
 
  // This file is part of the source of ApCoCoALib, the ApCoCoA Library.
 
  // This file is part of the source of ApCoCoALib, the ApCoCoA Library.
Line 16: Line 20:
 
  //  Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)
 
  //  Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)
 
  //
 
  //
  //  Author[s]: YEAR[S] NAME[S] OF AUTHOR[S]
+
  //  Author[s]: YEAR[S], NAME[S] OF AUTHOR[S]
 
  //
 
  //
 
  // Visit http://apcocoa.org/ for more information regarding ApCoCoA
 
  // Visit http://apcocoa.org/ for more information regarding ApCoCoA
Line 36: Line 40:
 
  // along with ApCoCoALib; if not, write to the Free Software
 
  // along with ApCoCoALib; if not, write to the Free Software
 
  // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 
  // 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==
 
==Namespace issues==
Line 43: Line 58:
 
  namespace ApCoCoA{
 
  namespace ApCoCoA{
 
   namespace AlgebraicCore{}
 
   namespace AlgebraicCore{}
   namespace NumericCore{}
+
   namespace NumericalCore{}
 
   namespace AlgebraicAlgorithms{}
 
   namespace AlgebraicAlgorithms{}
   namespace NumericAlgorithms{}
+
   namespace NumericalAlgorithms{}
 
  }
 
  }
  

Latest revision as of 10:37, 6 March 2008

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.