| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
|---|
| 5 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
|---|
| 6 | */
|
|---|
| 7 |
|
|---|
| 8 | /**
|
|---|
| 9 | * \file code.dox
|
|---|
| 10 | *
|
|---|
| 11 | * Created on: Oct 28, 2011
|
|---|
| 12 | * Author: heber
|
|---|
| 13 | */
|
|---|
| 14 |
|
|---|
| 15 | /**
|
|---|
| 16 | * \page code How to use and extend the code
|
|---|
| 17 | *
|
|---|
| 18 | * \section code-introduction How to understand the code
|
|---|
| 19 | *
|
|---|
| 20 | * \subsection code-introduction-whats-there What's there already ...
|
|---|
| 21 | *
|
|---|
| 22 | * Generally, you will begin by having to add a certain Action to the code.
|
|---|
| 23 | * Refer to the \ref constructs and (at the very least briefly) go through
|
|---|
| 24 | * all the stuff that is already there. This should give you an idea of what
|
|---|
| 25 | * you do not have to re-invent!
|
|---|
| 26 | *
|
|---|
| 27 | * As soon as you have decided upon all the little things required for your
|
|---|
| 28 | * Action, e.g. you need a LinkedCell construct because of nearest neighbor,
|
|---|
| 29 | * additionally you need access to BondGraph because you need bond distance
|
|---|
| 30 | * information, you want to know how to access and use each of these.
|
|---|
| 31 | *
|
|---|
| 32 | * \subsection code-introduction-whats-not-there What's not there ...
|
|---|
| 33 | *
|
|---|
| 34 | * Not everything is always documented, not everything is always up-to-date.
|
|---|
| 35 | * Search the code or try to look at Actions that are similar to what you
|
|---|
| 36 | * intent. Try to understand how they do and whever your ideas really can't
|
|---|
| 37 | * be realized with the current capabilities of the code.
|
|---|
| 38 | *
|
|---|
| 39 | * If not, it gets more complicated because if one extends the code, one can
|
|---|
| 40 | * proceed in a straight-forward and soon-to-reach-the-goal way or one can
|
|---|
| 41 | * try to realize if one's not generalizing a concept already present and
|
|---|
| 42 | * implement this generalization (and also bring what's already there up to
|
|---|
| 43 | * speed with this new implementation). Of course, before this "refactoring"
|
|---|
| 44 | * (http://en.wikipedia.org/wiki/Code_refactoring) one should have tests in
|
|---|
| 45 | * place that safeguard that the old functionality remains the same, see
|
|---|
| 46 | * \ref tests. From this generalization your concept should then be easier
|
|---|
| 47 | * to implement.
|
|---|
| 48 | *
|
|---|
| 49 | * Last but not least, see \ref future for what some of the areas are where
|
|---|
| 50 | * the code needs extension or refactorization. Maybe somethings close to what
|
|---|
| 51 | * you want and you could do it along the way, at the same time getting to
|
|---|
| 52 | * know the code better?
|
|---|
| 53 | *
|
|---|
| 54 | * \section code-howto-use How to use the code
|
|---|
| 55 | *
|
|---|
| 56 | * There are two things that should make it easy for you to get to know the
|
|---|
| 57 | * constructs, i.e. classes, required for your Action besides the documentation
|
|---|
| 58 | * and serve as tiny examples on how to use them:
|
|---|
| 59 | * - unit tests
|
|---|
| 60 | * - regression tests
|
|---|
| 61 | *
|
|---|
| 62 | * \subsection code-howto-use-unit-tests Unit tests
|
|---|
| 63 | *
|
|---|
| 64 | * Unit tests give you an idea how to use a specific constructs, e.g. they
|
|---|
| 65 | * tell you where to get it (simply \code new LinkedCell \endcode, or rather
|
|---|
| 66 | * \code World::getInstance().getBondGraph() \endcode, because it's a unique
|
|---|
| 67 | * instance) and how to use them because that's exactly what's being tested
|
|---|
| 68 | * there. Just browse through the various(?) test functions implemented in
|
|---|
| 69 | * each of the unit tests or rather the unit tests to the constructs you need.
|
|---|
| 70 | *
|
|---|
| 71 | * \subsection code-howto-use-regression-tests Regression tests
|
|---|
| 72 | *
|
|---|
| 73 | * Regression tests (\ref tests-regressiontests) give you an idea how your
|
|---|
| 74 | * Action eventually can be called (from the command line), what to put in your
|
|---|
| 75 | * \b .def file and how it ends up being the option you have to give.
|
|---|
| 76 | *
|
|---|
| 77 | * \attention Never forget that you are supposed to add a regression test for
|
|---|
| 78 | * your new Action as well, either right now (http://en.wikipedia.org/wiki/Test-driven_development)
|
|---|
| 79 | * or at the very latest once its finished.
|
|---|
| 80 | *
|
|---|
| 81 | * \subsection code-howto-use-last Last but not least
|
|---|
| 82 | *
|
|---|
| 83 | * Search the code with the desired construct as keyword to find out places
|
|---|
| 84 | * where it is internally used, see how it is done there and do the same
|
|---|
| 85 | * in your own Action.
|
|---|
| 86 | *
|
|---|
| 87 | * \section code-introduction-howto-extend How to extend the code
|
|---|
| 88 | *
|
|---|
| 89 | * Once you're certain your requirements are not met, new classes have to be
|
|---|
| 90 | * added. Do some careful thinking whether you add something altogether new or
|
|---|
| 91 | * whether it's already present in some simpler or slightly other form. In the
|
|---|
| 92 | * latter case, try to generalize what's present and build from there. E.g.
|
|---|
| 93 | * FormatParserParameters have been generalized from a simpler implementation
|
|---|
| 94 | * that was just used for the parameters for MpqcParser (know FormatParser<mpqc>
|
|---|
| 95 | * which has been refactored as well). Don't always go all the way, but extend
|
|---|
| 96 | * and generalize when it makes sense, especially when the code is much easier
|
|---|
| 97 | * to use afterwards or just much more powerful (with immediate consequences).
|
|---|
| 98 | *
|
|---|
| 99 | * Again, refer to \ref future to know what's already on the schedule, i. e.
|
|---|
| 100 | * what's already marked for extension or refactoring.
|
|---|
| 101 | *
|
|---|
| 102 | * \section code-reference Further readings
|
|---|
| 103 | *
|
|---|
| 104 | * \li \ref faq
|
|---|
| 105 | * \li \ref constructs
|
|---|
| 106 | * \li \ref howto
|
|---|
| 107 | *
|
|---|
| 108 | *
|
|---|
| 109 | * \date 2011-11-03
|
|---|
| 110 | *
|
|---|
| 111 | */
|
|---|
