/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file code.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */

/**
 * \page code How to use and extend the code
 *
 * \section code-introduction How to understand the code
 *
 * \subsection code-introduction-whats-there What's there already ...
 *
 * Generally, you will begin by having to add a certain Action to the code.
 * Refer to the \ref constructs and (at the very least briefly) go through
 * all the stuff that is already there. This should give you an idea of what
 * you do not have to re-invent!
 *
 * As soon as you have decided upon all the little things required for your
 * Action, e.g. you need a LinkedCell construct because of nearest neighbor,
 * additionally you need access to BondGraph because you need bond distance
 * information, you want to know how to access and use each of these.
 *
 * \subsection code-introduction-whats-not-there What's not there ...
 *
 * Not everything is always documented, not everything is always up-to-date.
 * Search the code or try to look at Actions that are similar to what you
 * intent. Try to understand how they do and whever your ideas really can't
 * be realized with the current capabilities of the code.
 *
 * If not, it gets more complicated because if one extends the code, one can
 * proceed in a straight-forward and soon-to-reach-the-goal way or one can
 * try to realize if one's not generalizing a concept already present and
 * implement this generalization (and also bring what's already there up to
 * speed with this new implementation). Of course, before this "refactoring"
 * (http://en.wikipedia.org/wiki/Code_refactoring) one should have tests in
 * place that safeguard that the old functionality remains the same, see
 * \ref tests. From this generalization your concept should then be easier
 * to implement.
 *
 * Last but not least, see \ref future for what some of the areas are where
 * the code needs extension or refactorization. Maybe somethings close to what
 * you want and you could do it along the way, at the same time getting to
 * know the code better?
 *
 * \section code-howto-use How to use the code
 *
 * There are two things that should make it easy for you to get to know the
 * constructs, i.e. classes, required for your Action besides the documentation
 * and serve as tiny examples on how to use them:
 * - unit tests
 * - regression tests
 * 
 * \subsection code-howto-use-unit-tests Unit tests
 *
 * Unit tests give you an idea how to use a specific constructs, e.g. they
 * tell you where to get it (simply \code new LinkedCell \endcode, or rather
 * \code World::getInstance().getBondGraph() \endcode, because it's a unique
 * instance) and how to use them because that's exactly what's being tested
 * there. Just browse through the various(?) test functions implemented in
 * each of the unit tests or rather the unit tests to the constructs you need.
 *
 * \subsection code-howto-use-regression-tests Regression tests
 *
 * Regression tests (\ref tests-regressiontests) give you an idea how your
 * Action eventually can be called (from the command line), what to put in your
 * \b .def file and how it ends up being the option you have to give.
 *
 * \attention Never forget that you are supposed to add a regression test for
 * your new Action as well, either right now (http://en.wikipedia.org/wiki/Test-driven_development)
 * or at the very latest once its finished.
 *
 * \subsection code-howto-use-last Last but not least
 *
 * Search the code with the desired construct as keyword to find out places
 * where it is internally used, see how it is done there and do the same
 * in your own Action.
 *
 * \section code-introduction-howto-extend How to extend the code
 *
 * Once you're certain your requirements are not met, new classes have to be
 * added. Do some careful thinking whether you add something altogether new or
 * whether it's already present in some simpler or slightly other form. In the
 * latter case, try to generalize what's present and build from there. E.g.
 * FormatParserParameters have been generalized from a simpler implementation
 * that was just used for the parameters for MpqcParser (know FormatParser<mpqc>
 * which has been refactored as well). Don't always go all the way, but extend
 * and generalize when it makes sense, especially when the code is much easier
 * to use afterwards or just much more powerful (with immediate consequences).
 *
 * Again, refer to \ref future to know what's already on the schedule, i. e.
 * what's already marked for extension or refactoring.
 *
 * \section code-reference Further readings
 *
 * \li \ref faq
 * \li \ref constructs
 * \li \ref howto
 *
 *
 * \date 2011-11-03
 *
 */