Documentation

Back to Coding Standards

General rules for writing comments in code:

• All comments are written in English.
• Prefer C++-style comments // instead of C-style comments /*…*/ (exception: doxygen documentation).

Each source-code file starts with an introductory comment including

• the current svn revision (automatically filled by svn);
• the author and date of the last checkin (automatically filled by svn);
• a brief description of the files's purpose;
• the author of the source code (these are the developers that have done a substantial contribution to the code);
• the GPL license text.

The text between $…$ is automatically substituted by svn when committing a new revision. Please observe that the pattern is not changed (e.g., by omitting the last '$'), otherwise svn substitution will not work! It is also important that the doxygen keywords (\file, \brief, \author, \par, \see) are not changed in order to guarantee proper generation of the reference documentation.

/*
 * $Revision: 1.17 $
 * 
 * last checkin:
 *   $Author: gutwenger $ 
 *   $Date: 2008-01-26 15:44:58 +0100 (Sa, 26 Jan 2008) $ 
 ***************************************************************/
 
/** \file
 * \brief Declaration of doubly linked lists and iterators
 * 
 * \author Carsten Gutwenger and Sebastian Leipert
 * 
 * \par License:
 * This file is part of the Open Graph Drawing Framework (OGDF).
 * Copyright (C) 2005-2007
 * 
 * \par
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * Version 2 or 3 as published by the Free Software Foundation
 * and appearing in the files LICENSE_GPL_v2.txt and
 * LICENSE_GPL_v3.txt included in the packaging of this file.
 *
 * \par
 * In addition, as a special exception, you have permission to link
 * this software with the libraries of the COIN-OR Osi project
 * (http://www.coin-or.org/projects/Osi.xml), all libraries required
 * by Osi, and all LP-solver libraries directly supported by the
 * COIN-OR Osi project, and distribute executables, as long as
 * you follow the requirements of the GNU General Public License
 * in regard to all of the software in the executable aside from these
 * third-party libraries.
 * 
 * \par
 * This program 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.
 * 
 * \par
 * You should have received a copy of the GNU General Public 
 * License along with this program; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 * 
 * \see  http://www.gnu.org/copyleft/gpl.html
 ***************************************************************/

We use doxygen to produce the OGDF's reference documentation directly from the source code. Please refer to the doxygen documentation for details about doxygen syntax.

• Document (at least) each member in the public interface of the code, e.g., public methods in a class.
• Each documented member must have a brief comment; if necessary provide also a long comment and document parameters of functions.
• Each class must have at least a brief comment; usually classes should have more detailed documentations that also includes usage of the class.

The comment style we use can be seen in the following example code (adapted excerpt from List.h):

//! The parameterized class \a ListPure<E> represents doubly linked lists with content type \a E.
/**
 * Elements of the list are instances of type ListElement<E>.
 * Use ListConstIterator<E> or ListIterator<E> in order to iterate over the list.
 * 
 * In contrast to List<E>, instances of \a ListPure<E> do not store the length of the list.
 */
template<class E> class ListPure
{
protected:
    ListElement<E> *m_head; //!< Pointer to first element.
    ListElement<E> *m_tail; //!< Pointer to last element.
 
public:
    //! Constructs an empty doubly linked list.
    ListPure() : m_head(0), m_tail(0) { }
 
    //! Returns the length of the list.
    /**
     * Notice that this method requires to run through the whole list and takes linear running time!
     */
    int size() const;
 
    //! Inserts element \a x before or after \a it.
    /**
     * @param x is the element to be inserted.
     * @param it is a list iterator in this list.
     * @param dir determines if \a x is inserted before or after \a it.
     *        Possible values are \c ogdf::before and \c ogdf::after.
     * \pre \a it points to an element in this list.
     */
    ListIterator<E> insert(const E &x, ListIterator<E> it, Direction dir = after);
};