% =============================================================================
% The CGAL Developers' Manual
% Chapter: Coding Conventions
% -----------------------------------------------------------------------------
% file   : coding.tex
% authors: Sven Schönherr <sven@inf.ethz.ch>
% -----------------------------------------------------------------------------
% $Revision$
% $Date$
% =============================================================================


\chapter{Coding Conventions} 
\label{chap:code_format}

\ccChapterRelease{Chapter Version: 1.1} \\
\ccChapterAuthor{Sven Sch{\"o}nherr ({\tt sven@inf.ethz.ch})}

We do not want to impose very strict coding rules on the developers.
What is most important is to follow the \cgal\ naming scheme 
described in the next section. We recommend the use of 
\ccAnchor{http://shelob.ce.ttu.edu/daves/lpfaq/faq.html}{\emph{literate programming}} tools\ccIndexMainItemDef{literate programming}, 
\ccIndexSubitem{tools}{literate programming}
\ccIndexSubitem{documentation}{of implementation}
such as \ccAnchor{http://www.ross.net/funnelweb/}{\texttt{funnelweb}}%
\ccIndexMainItem{\tt funnelweb},
\ccAnchor{http://www-cs-faculty.stanford.edu/~knuth/cweb.html}{\texttt{cweb}},%
\ccIndexMainItem{\tt cweb}
or
\ccAnchor{http://www.eecs.harvard.edu/~nr/noweb/}{\texttt{noweb}},%
\ccIndexMainItem{\tt noweb}
but this is up to the developer. However, there
are some programming conventions
(Section~\ref{sec:programming_conventions}) that should be adhered to, 
rules for the code format
(Section~\ref{sec:code_format}), and a mandatory heading for each
source file (Section~\ref{sec:file_header})


% -----------------------------------------------------------------------------
\section{Naming scheme} 
\label{sec:naming_scheme}
\ccIndexMainItemBegin{naming scheme}

The \cgal\ naming scheme is intended to help the user 
use the library and the developer develop the
library. The rules are simple and easy to remember. Where appropriate,
they aim for similarity with the names used in the \stl. Deviations from the
given rules should be avoided; however, exceptions are possible if
there are \emph{convincing} reasons.

\subsection*{General rules}

\begin{itemize}
\item Words in a name should be separated by underscores. For example,
      one would use \ccc{function_name} and \ccc{Class_name} instead of
      \ccc{functionName} and \ccc{Classname}.
      \ccIndexSubitem{naming scheme}{word separators}
      \ccIndexSubitem{naming scheme}{underscores}
      You may notice that this rule is sometimes violated in the names of
      template parameters, where names follow the \stl\ naming scheme.  That
      is,  each word starts with a capital letter 
      and the words are catenated together without any delimiter, 
      (\eg, \ccc{InputIterator}).  This exception is tolerated (and, in some
      cases such as the iterators, encouraged).
\item Abbreviations of words are to be avoided%
      \ccIndexSubitem{naming scheme}{abbreviations}
      ({\em e.g.}, use 
      \ccc{Triangulation} instead of \ccc{Tri}).  The only exceptions
      might be standard geometric abbreviations (such as ``CH'' for ``convex
      hull'') and standard data structure abbreviations (such as ``DS'' for
      ``data structure'').  Unfortunately, the long names that result from
      the absence of abbreviations are known to cause problems with some 
      compilers.\ccIndexMainItem{long-name problem}
%      See Section~\ref{sec:long_name_problem}
%      for further information about the so-called ``long-name problem.''

\ccIndexSubitemBegin{naming scheme}{capitalization}
\item Names of constants are uppercase ({\em e.g.}, \ccc{ORIGIN}).
      \ccModifierCrossRefOff
      \ccIndexSubitem{constants, global}{naming}
      \ccModifierCrossRefOn
\item The first word of a class or enumeration name should be capitalized
      ({\em e.g.}, \ccc{Quotient}, \ccc{Orientation}).
      \ccIndexSubitem{classes}{naming}
      \ccIndexSubitem{enumerations}{naming}
\item Function names are in lowercase
      ({\em e.g.}, \ccc{is_zero}).
      \ccIndexSubitem{functions}{naming}
\ccIndexSubitemEnd{naming scheme}{capitalization}
\item Boolean function names should begin with a verb.  For example, use
      \ccc{is_empty} instead of simply \ccc{empty} and 
      \ccc{has_on_bounded_side} instead of \ccc{on_bounded_side}.%
      \ccIndexSubitem{functions}{naming}%
      \ccIndexSubitem{naming scheme}{boolean functions}%
      \ccIndexSubitem{naming scheme}{predicates}
\item Names of macros should begin with the prefix \ccc{CGAL_}.
      \ccIndexSubitem{macros}{naming}
\end{itemize}

\subsection*{Geometric objects}
\ccIndexSubitemBegin{naming scheme}{geometric objects}
\ccIndexSubitemBegin{naming scheme}{dimension number}
\ccIndexSubitemBegin{geometric objects}{naming}

\begin{itemize}
\item All geometric objects have the dimension as a suffix (\eg, \ccc{Vector_2}
      and \ccc{Plane_3}).
     \textbf{Exception:} For $d$-dimensional objects there may be a dynamic 
     and a static version. The former has the suffix \ccc{_d} 
     (\eg, \ccc{Point_d}), while the latter has the dimension as the first 
     template parameter (\eg, \ccc{Point<d>}).  
\end{itemize}
\ccIndexSubitemEnd{geometric objects}{naming}
\ccIndexSubitemEnd{naming scheme}{dimension number}
\ccIndexSubitemEnd{naming scheme}{geometric objects}

\subsection*{Geometric data structures and algorithms}
\ccIndexSubitemBegin{naming scheme}{data structures}
\ccIndexSubitemBegin{naming scheme}{algorithms}
\ccIndexSubitemBegin{data structures}{naming}
\begin{itemize}
\item Names for geometric data structures and algorithms should follow
      the ``spirit'' of the rules given so far, \eg~a data structure for
      triangulations in the plane is named \ccc{Triangulation_2}, and a
      convex hull algorithm in 3-space is named \ccc{convex_hull_3}.
\item Member functions realizing predicates should start with \ccc{is_} or
      \ccc{has_}, \eg~the data structure \ccc{Min_ellipse_2} has member 
      functions \ccc{is_empty} and \ccc{has_on_bounded_side}.
      \ccIndexSubitem{naming scheme}{predicates}
\item Access to data structures is given via iterators and
      circulators (Chapter~\ref{chap:iterators_and_circulators}).  
      For iterators and functions 
      returning them we extend
      the \stl\ names with a prefix describing the items to be accessed.
      For example, the functions \ccc{vertices_begin} and \ccc{vertices_end}
      return a \ccc{Vertex_iterator}. (Note that we use the name of the items 
      in singular for the iterator type name and in plural for the functions
      returning the iterator.) Names related to circulators are handled
      similarly, using the suffix \ccc{_circulator}. For example, the
      function \ccc{edges_circulator} returns an \ccc{Edge_circulator}.
      \ccIndexSubitem{naming scheme}{iterators}
      \ccIndexSubitem{naming scheme}{circulators}
      \ccIndexSubitem{naming scheme}{access functions}
      \ccIndexSubitem{iterators}{naming}
      \ccIndexSubitem{circulators}{naming}
      \ccIndexSubitem{access functions}{naming}
\end{itemize}
\ccIndexSubitemEnd{data structures}{naming}
\ccIndexSubitemEnd{naming scheme}{algorithms}
\ccIndexSubitemEnd{naming scheme}{data structures}


\subsection*{Kernel traits}
\ccIndexSubitemBegin{naming scheme}{kernel traits}
\ccIndexSubitemBegin{kernel traits}{naming scheme}
\ccIndexMainItemBegin{function objects}

With the goal in mind of allowing the kernel to be used as a default
traits class for most data structures and algorithms, the following naming
scheme was devised for kernel traits class objects.  All types in the
kernel traits class are function object types\footnote{Technically, one
should speak of function classes or function object classes, but the term
``function object'' has become prevalent.}, and we 
distinguish the following four categories:
\begin{enumerate}
\item\textbf{generalized predicates} \ie,~standard predicates
       returning a Boolean value as well as functions such as 
       \ccc{orientation()} that return an
       enumeration type (values from a finite discrete set).
\item\textbf{construction objects}, which replace constructors in the kernel,
\item\textbf{constructive procedures} and
\item\textbf{function objects replacing operators}.
\end{enumerate}

\ccIndexSubitemBegin{function objects}{naming}
As detailed below, the names of these function objects reflect the actions
performed by calls to \ccc{operator()}.   This naming scheme was 
chosen instead of one in which the computed object determines the name because
this latter naming scheme is more natural for functions that compute values
where the function call can be seen as a name for the object returned
instead of function objects that simply maintain data associated with the
computation.  It was also noted that the naming of functions and function
objects is not consistent,
either in \cgal\ or in the \stl\ (In some cases the action performed by a 
function determines its name (\eg, \ccc{multiply()}) while in others the
result of the action determines the name (\eg, \ccc{product()}).), so 
achieving complete consistency with an existing naming scheme is not possible.

Here are the naming rules:
\begin{itemize}
\item All names in the kernel traits have the dimension as a suffix.
      This is necessary because in some cases (\eg, the \ccc{Orientation_2}
      object) the absence of the suffix would cause a name conflict with
      an existing type or class (\eg, the enumeration type \ccc{Orientation}).
\item The names of generalized predicates are determined by their results.
      Furthermore, names are as much as possible consistent with the current
      kernel and the \stl. So, for example, we have objects like
      \ccc{Has_on_bounded_side_2}, \ccc{Is_degenerate_2}, and
      \ccc{Is_horizontal_2}.  According to the current kernel we also have
      \ccc{Leftturn_2}.  For reasons of consistency with \stl, all
      ``less-than''-objects start with \ccc{Less_}, \eg,~\ccc{Less_xy_2}.
      Further examples are \ccc{Less_distance_to_point_2} and
      \ccc{Less_distance_to_line_2}. However, we have \ccc{Equal_2},
      whereas the corresponding \stl\ function object is called
      \ccc{equal_to}. Here, we give our dimension rule higher priority. As
      a special object, we also have an \ccc{Equal_xy_2} for checking
      coincidence of points with respect to $x$ and $y$ coordinates.
\item The names of construction objects (category 2 above) follow the pattern 
      \ccc{Construct_{\tt type_d}}, where \texttt{type\_d} is the type 
      constructed, \eg,~\ccc{Construct_point_2} and \ccc{Construct_line_2}.  
      The \ccc{operator()} of these function object classes is overloaded.
      This reduces the number of names to remember drastically, while
      replacing one of the constructions gets more complicated, but is
      still possible.
\item Function objects in category 3 above can be further subdivided into
      two classes:
      \begin{itemize}
         \item constructive procedures that construct objects whose types are 
               known {\em a priori}
         \item procedures that construct objects whose types are not known 
               {\em a priori}
      \end{itemize}

      The names of function objects in the first class also start with 
      \ccc{Construct_} whenever a geometric object is constructed, otherwise 
      they start with \ccc{Compute_}.  Here, real numbers are not considered 
      to be 1-dimensional geometric objects.  For example, on the one hand 
      we have \ccc{Construct_perpendicular_vector_2}, 
      \ccc{Construct_midpoint_3},
      \ccc{Construct_circumcenter_d}, \ccc{Construct_bisector_2}, and
      \ccc{Construct_point_on_3}, while on the other hand there are
      \ccc{Compute_y_at_x_2} and \ccc{Compute_squared_length_3}.  

      For the second class, the names of the objects describe the (generic) 
      action, \eg~\ccc{Intersect_2}.
\item The equality operator (\ccc{operator==()}) is replaced by function 
      objects with names of the form \ccc{Equal_{\tt k}}, where {\tt k} is 
      the dimension number (\ie, 2, 3, or \ccc{d}). 
      For replacing arithmetic operators, we might also provide \ccc{Add_2},
      \ccc{Subtract_2}, \ccc{Multiply_2}, and \ccc{Divide_2}. (As mentioned
      above, the action determines the name, not the result.) We think
      that these objects are not really needed.  They are likely to be
      part of primitive operations that have a corresponding function
      object in the traits.
\end{itemize}
\ccIndexSubitemEnd{kernel traits}{naming scheme}
\ccIndexSubitemEnd{function objects}{naming}
\ccIndexMainItemEnd{function objects}

In addition, for each function object the kernel traits class has
a member function that returns an instance of this function object.
The name of this function should be the (uncapitalized) name of the
function object followed by the suffix \ccc{_object}.%
%\index{object functions@{\ccFont \_object} functions} 
For example, the function that retuns an instance of the \ccc{Less_xy_2} 
function object is called \ccc{less_xy_2_object}.
\ccIndexSubitemEnd{naming scheme}{kernel traits}

\subsection*{File names}
\ccIndexSubitemBegin{naming scheme}{source files}
\ccIndexSubitemBegin{source files}{naming scheme}

\begin{itemize}
\item File names should be chosen in the ``spirit'' of the naming rules given
      above.
\item If a single geometric object, data structure, or algorithm is provided
      in a single file, its name (and its capitalization) should be used for 
      the file name. For
      example, the file \ccc{Triangulation_2.h} contains the data structure 
      \ccc{Triangulation\_2}.
\item If a file does not contain a single class, its name should not begin
      with a capital letter.
\end{itemize}
\ccIndexSubitemEnd{source files}{naming scheme}
\ccIndexSubitemEnd{naming scheme}{source files}
\ccIndexMainItemEnd{naming scheme}


% -----------------------------------------------------------------------------
\section{Programming conventions} 
\label{sec:programming_conventions}
\ccIndexMainItemBegin{programming conventions}

The first list of items are meant as rules, \ie,~you should follow them.

\begin{itemize}
\item Give typedefs for all template arguments of a class that may be
      accessed later from outside the class, \eg, 
  \begin{verbatim}
  template < class Arg_ >
  class Something {
    public:
      typedef  Arg_  Arg;
  };
  \end{verbatim}
  As a general rule the template parameters should have the same name
  as the typedef, followed by an underscore.  (Note that using a preceding
  underscore is not allowed according to the \CC\ standard; all such names
  are reserved.)\index{C++ standard@\CC\ standard!underscores}%
  \ccIndexSubitem{underscores}{in names}%
  \ccIndexSubitem{naming scheme}{underscores}%
  \ccIndexSubitem{naming scheme}{template parameters}%
\item Use \ccc{const} when a call by reference argument is not
      modified, e.g.~\ccc{int f( const A& a)}%
     \index{call by reference!const and@{\ccFont const} and}.
\item Use \ccc{const} to indicate that a member function does not
      modify the object to which it is applied,
      \eg,~\ccStyle{class A \{ int f( void) const; \};}. This should be also
      done when it is only conceptually \ccc{const}%
      \index{conceptual const-ness@conceptual {\ccFont const}-ness|textbf}.
      This means that the member function \ccc{f()} is {\ccFont const} as seen from 
      the outside, but internally it may modify some data members 
      that are declared {\ccFont mutable}\ccIndexMainItem{\ccFont mutable}. An example 
      is the caching of results from expensive computations.  For more 
      information about conceptually {\ccFont const} functions and mutable data 
      members see \cite{Meyers97}.
\item Prefer \CC-style to C-style casts,%
      \index{casts!C++-style vs. C-style@\CC- style vs. C-style}
      \eg,~use \ccc{static_cast<double>( i)} instead of {\ccFont (double)i}.
\item Protect header files against multiple inclusion,
      \ccIndexSubitem{header files}{multiple inclusion of}
      \eg~the file {\tt This\_is\_an\_example.h} should begin/end with
      \begin{verbatim}
         #ifndef CGAL_THIS_IS_AN_EXAMPLE_H
         #define CGAL_THIS_IS_AN_EXAMPLE_H
         ...
         #endif // CGAL_THIS_IS_AN_EXAMPLE_H
     \end{verbatim}
\end{itemize}

The following items can be seen as recommendations 
in contrast to the rules of previous paragraph.

\begin{itemize}
\item The macro \verb|#define| should be used sparingly.
\item Try to avoid renaming the base types of \CC\ using {\ccFont typedef}.
\item When using an overloaded call, always give the exact match. Use
      explicit casting if necessary.
\end{itemize}
\ccIndexMainItemEnd{programming conventions}


% -----------------------------------------------------------------------------
\section{Code format} 
\label{sec:code_format}
\ccIndexMainItemBegin{code format}

\begin{itemize}
\item Lines should not exceed 80 characters.%
      \ccIndexSubitem{code format}{line length}
\item Use indentation with at least two spaces extra per level.%
      \ccIndexSubitem{code format}{indentation}
\item Write only one statement per line.
\item Use \CC-style comments, \eg,~{\ccFont // some comment}.%
      \ccIndexSubitem{code format}{comments}
\item Remove line pragmas, \ie,~\verb|#line...|.% 
      (See Section~\ref{sec:remove_line_directives}.)
\end{itemize}
\ccIndexMainItemEnd{code format}


% -----------------------------------------------------------------------------
\section{File header} 
\label{sec:file_header}
\ccIndexSubitemBegin{source files}{headings for}

Each \cgal\ source file must start with a heading that allows for an easy
identification of the file. The file header contains a copyright notice, the
current release number and date, and a description of the file.

\subsection*{Internal releases}
\ccIndexSubsubitemBegin{source files}{headings for}{internal releases}

The heading of a \cgal\ source file that is submitted (for an internal release)
should have the following format:

\begin{verbatim}
// ============================================================================
//
// Copyright (c) 1997-2000 The CGAL Consortium
//
// This software and related documentation is part of an INTERNAL release
// of the Computational Geometry Algorithms Library (CGAL). It is not
// intended for general use.
//
// ----------------------------------------------------------------------------
//
// release       : $CGAL_Revision$
// release_date  : $CGAL_Date$
//
// file          : include/CGAL/Min_ellipse_2.h
// package       : Min_ellipse_2 (3.5.4)
// chapter       : Geometric Optimisation
//
// source        : web/Optimisation/Min_ellipse_2.aw
// revision      : $Revision$
// revision_date : $Date$
//
// author(s)     : Bernd Gaertner, Sven Schoenherr
// maintainer    : Sven Schoenherr <sven@inf.fu-berlin.de>
// coordinator   : ETH Zuerich (Bernd Gaertner <gaertner@inf.ethz.ch>)
//
// implementation: 2D Smallest Enclosing Ellipse
// ============================================================================
\end{verbatim}

The following rules apply to the fields:
%
\begin{itemize}
\item {\tt <release>}, {\tt <release\_date>}, and {\tt <maintainer>} must be 
      present but need not be filled in (since they will be overwritten when 
      the internal release is created). 
\item {\tt <file>}, {\tt <package>}, {\tt <author(s)>}, and
      {\tt <coordinator>} are obligatory and must be filled in.
\item {\tt <chapter>}, {\tt <source>}, {\tt <revision>}, {\tt <revision\_date>},
      and {\tt <implementation>} are optional.
\item For the {\tt <coordinator>} field, the coordinating site as well as
      the person in charge is named, together with the person's e-mail address.
\item Optionally, the next-to-last line may contain a comment on the
      functionality of the source file's content.
\end{itemize}
%
When a new internal release is generated\ccIndexMainItem{internal release}, 
the fields {\tt <release>} and {\tt <release\_date>} are overwritten. 
The release label for the internal release is composed of the number of the 
next public release, an~{\tt I} (for ``internal''), and a positive integer that 
represents the internal release number (\eg, e.g.~{\tt CGAL-2.2-I-1} was the 
number of the first internal release after public release 2.1).%
\ccIndexSubitem{internal release}{number} 
If the field {\tt <maintainer>} is blank, it is filled in with the name and
email address of the last person who submitted the package.%
\ccIndexSubitem{\tt maintainer}{field in file header} 
All other fields between the two delimiting 
lines of equal signs remain untouched.
\ccIndexSubsubitemEnd{source files}{headings for}{internal releases}


\subsection*{Public releases}
\ccIndexSubsubitemBegin{source files}{headings for}{public releases}

When a new public release is generated, only the fields {\tt <file>},
{\tt <package>}, \mbox{{\tt <chapter>}} (if present), and {\tt <author(s)>}
are kept.  The heading of the source file will become something like this:
%
\begin{verbatim}
// ============================================================================
//
// Copyright (c) 1997-2000 The CGAL Consortium
//
// This software and related documentation is part of the
// Computational Geometry Algorithms Library (CGAL).
//
// This software and documentation is provided "as-is" and without warranty
// of any kind. In no event shall the CGAL Consortium be liable for any
// damage of any kind.
//
// Every use of CGAL requires a license. 
//
// Academic research and teaching license
// - For academic research and teaching purposes, permission to use and copy
//   the software and its documentation is hereby granted free of charge,
//   provided that it is not a component of a commercial product, and this
//   notice appears in all copies of the software and related documentation. 
//
// Commercial licenses
// - A commercial license is available through Algorithmic Solutions,
//   who also markets LEDA (http://www.algorithmic-solutions.com). 
// - Commercial users may apply for an evaluation license by writing to
//   Algorithmic Solutions (contact@algorithmic-solutions.com).
//
// The CGAL Consortium consists of Utrecht University (The Netherlands),
// ETH Zurich (Switzerland), Freie Universität Berlin (Germany),
// INRIA Sophia-Antipolis (France), Martin-Luther-University Halle-Wittenberg
// (Germany), Max-Planck-Institute Saarbrucken (Germany), RISC Linz (Austria),
// and Tel-Aviv University (Israel).
//
// ----------------------------------------------------------------------------
//
// release       : CGAL-2.1
// release_date  : 2000, January 11
//
// file          : include/CGAL/Min_ellipse_2.h
// package       : Min_ellipse_2 (3.5.4)
// chapter       : Geometric Optimisation
// author(s)     : Bernd Gaertner, Sven Schoenherr
//
// email         : cgal@cs.uu.nl
//
// ============================================================================
\end{verbatim}
\ccIndexSubsubitemEnd{source files}{headings for}{public releases}
\ccIndexSubitemEnd{source files}{headings for}


\section{Requirements and recommendations}
\label{sec:code_format_doc_req_and_rec}

\noindent
Requirements:
\begin{itemize}
   \item Follow the naming schemes outlined above.
   \item Provide typedefs of template arguments as necessary to make the
         template parameters accessible elsewhere.
   \item Label member function and parameters with \ccc{const} where 
         appropriate
   \item Use \CC-style type casts.
   \item Protect header files from multiple inclusions.
   \item Obey the code format rules outlined above.
   \item Provide a header for each submitted file in the proper format.
\end{itemize}

\noindent
Recommendations:
\begin{itemize}
   \item Use literate programming tools to adequately document your 
         implementation.
\end{itemize}

% ===== EOF ===================================================================
