Difference between revisions of "ApCoCoALib:CodingGuidelines"

From ApCoCoAWiki
(→‎Namespace issues: use -> using)
(adding a link to ApCoCoA:CodingGuidelines)
 
(26 intermediate revisions by 6 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 standards unless noted otherwise.
+
Please follow the CoCoALib coding guidlines unless noted otherwise.
 +
A part of these rules can be found [[CoCoALib:CodingGuidelines|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==
 
==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.
 
  //
 
  //
  // Copyright YEAR[S], NAME[S] OF COPYRIGHT HOLDERS
+
  //   Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)
 
  //
 
  //
  // visit http://apcocoa.org/ for more information regarding ApCoCoA
+
  //   Author[s]: YEAR[S], NAME[S] OF AUTHOR[S]
 +
//
 +
// Visit http://apcocoa.org/ for more information regarding ApCoCoA
 
  // and ApCoCoALib.
 
  // and ApCoCoALib.
  // visit http://www.apcocoa.org/wiki/ApCoCoA:KnownIssues for bugs, problems  
+
  // Visit http://www.apcocoa.org/wiki/ApCoCoA:KnownIssues for bugs, problems  
 
  // and known issues.
 
  // and known issues.
 
  //
 
  //
 
  // ApCoCoALib is free software; you can redistribute it and/or modify
 
  // ApCoCoALib is free software; you can redistribute it and/or modify
  // it under the terms of the GNU General Public License (version 2)
+
  // 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
 
  // as published by the Free Software Foundation. A copy of the full
 
  // licence may be found in the file COPYING in this directory.
 
  // licence may be found in the file COPYING in this directory.
Line 26: Line 38:
 
  //
 
  //
 
  // You should have received a copy of the GNU General Public License
 
  // You should have received a copy of the GNU General Public License
  // along with ApCoCoA; 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==
Do not use "using" to automatically embedd namespaces, including std or CoCoA.  
+
Do not use "using" to automatically embed namespaces, including std or CoCoA.  
 
Include your code into the following namespace structure:
 
Include your code into the following namespace structure:
  
 
  namespace ApCoCoA{
 
  namespace ApCoCoA{
 
   namespace AlgebraicCore{}
 
   namespace AlgebraicCore{}
   namespace NumericCore{}
+
   namespace NumericalCore{}
 
   namespace AlgebraicAlgorithms{}
 
   namespace AlgebraicAlgorithms{}
   namespace NumericAlgorithms{}
+
   namespace NumericalAlgorithms{}
  namespace HybridAlgorithms{}
 
 
  }
 
  }
  
Line 61: Line 83:
  
 
  include/
 
  include/
     ./algebraical/
+
     ./Algebraical/
     ./numerical/
+
      ./Internal/
       ./ABM/
+
     ./Numerical/
  library.h
+
       ./Internal/
  numerical_library.h
+
  Library.h
  algebraical_library.h
+
  NumericalLibrary.h
 +
  AlgebraicalLibrary.h
  
the include directory contains three headers, algebraical_library.h, including all top-level headers, offering algebraical methods,
+
the include directory contains three headers, AlgebraicalLibrary.H, including all top-level headers, offering algebraical methods,
the numerical_library.h including all top-level methods which are not purely algebraical. So hybrid methods should be also in numerical.
+
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.
+
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.
 
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 sub-directory. E.g. the matrix class for ABM ABM::DoubleDenseMatrix is in the subdirectory ABM. A rule of thumb: the directory structure is very close to the namespace, excluding a distingtion between core and algorithms!
+
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===
 
===the source directory===
Analog to the header organisation, the source is splitted 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/ ).  
+
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 a distingtion between core and algorithms!
+
A rule of thumb: the directory structure is very close to the namespace, excluding the distinction between core and algorithms!
 
 
  
  
 
{{Stub}}
 
{{Stub}}
  
[[Category:ApCoCoA]]
+
[[Category:ApCoCoALib|{{PAGENAME}}]]

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.