(c) Copyright Rosetta Commons Member Institutions.
(c) This file is part of the Rosetta software suite and is made available under license.
(c) The Rosetta software is developed by the contributing members of the Rosetta Commons.
(c) For more information, see http://www.rosettacommons.org. Questions about this can be
(c) addressed to University of Washington UW TechTransfer, email: license@u.washington.edu.

Source file stubs
=================

Usage:
-----
Copy the following into your project's src/ directory:
  - The .fwd.hh, .hh and .cc for the desired stub category, renaming to
    fit your class.
  - package.fwd.hh, renaming to fit your package

Copy the following into your project's src/ directory:
  - XxxClass.dox, renaming to fit your class.
  - package.dox, renaming to fit your class

Change all references to XxxClass (where Xxx is the stub category) in
your new files into the class name.

Change all references to "project" and "subproject" in the namespaces
and include guards to match your package hierarchy.  There may of course
be fewer or more than two nestings: "project" and "subproject" are chosen
just to illustrate.


File types:
-----------
  *.fwd.hh - Header files with forward declarations for the class contained
             in the equivalent *.hh.   The .hh will include the .fwd.hh as
             its first header.
             If no classes are present then there is no .fwd.hh: all forward
             declared free functions live in a .hh as per normal.
             *.fwd.hh exists to improve compilation time.  Anytime the
             class is being used by pointer, smart pointer or reference only
             the .fwd.hh should be included instead of the .hh
  *.hh     - Header file templates
  *.cc     - Source file templates.
  *.dox    - Doxygen templates.

  <package>.fwd.hh -
            Header for the forward declarations of the entire package.
            This should #include all the other .fwd.hh files.  If this affects
            compilation time adversely, individual .fwd.hh files should be used
            instead.
  <package>.dox -
            Doxygen file for the entire package.


Stub categories:
----------------

Interface is an purely abstract interface.  It is never instantiated and has
no fields.  It's definition is extremely restricted.
  - Can derive from other interfaces.
  - There is only a header (.hh), and a forwards header (.fwd.hh).
  - Destructor is public and defined inline empty.
  - A single protected constructor exists and is defined inline empty.
  - No other constructors (including operator=) are allowed (for idiom's
    sake: no fields exist.)
  - All other methods must be pure virtual (= 0).  They may not have
    definitions.
  - There are no fields.
  - No private sections exist.


BaseClass is a abstract base class, designed only for subclassing.
  - Does not derive from anything.
  - Destructor is public and virtual.
  - Constructors are protected.
  - Copy constructor/assignment are private and should be left undefined
    unless they are explicitly needed.  If so they should be made protected.
  - Most, if not all fields, should be private (expose them via properties).


DerivedClass is a class intended to be derived from another class.  In
turn it can act as a base class.
  - Can derive from a BaseClass or an Interface.
  - Destructor is public and virtual.
  - Constructors are public or protected.
  - Copy constructor/assignment are private and should be left undefined
    unless they are explicitly needed.  If so they should be made public.


FinalClass is a class intended to be derived from another base class but
not be derived in turn.
  - Destructor is public and virtual.
  - Constructor/destructor are public.
  - Copy constructor/assignment are public.
  - No protected sections exist.


StandaloneClass is not derived from another class nor will it be used as
a base class.
  - Destructor is public and NOT virtual.
  - Constructors are public.
  - Copy constructor/assignment are public.
  - No protected sections exist.


In all cases methods are defined in the .cc files.  If you want them to be
inline you should move them to the .hh file.  They are also deliberately
commented out: you do not want them to accidentally be defined incorrectly.
But they are there for convenience and can be uncommented to save on some
typing.


Sections:
---------

Sections are divided by purpose.  The goal is to group related items
together.  The followings section are likely to exist in most classes:

  - Friends: Any friend types, or friend functions NOT DEFINED in the
    class.

  - Types:  Any types defined, or imported by using statements.

  - Creation:  Constructors of all kinds and destructors.

  - Methods:  Any operations on the class, including overloaded operators,
    virtual and non-virtual methods, static methods, and friend functions
    closely associated with the class.

  - Properties:  Methods which provide a level of encapsulation for
    fields.  Properties allow read and write access to fields (aka "get"
    and "set" methods).  However they are not necessarily represented by
    actual fields, and be calculated or created on the fly.

    A property logically corresponds to:

        x = Object.property;            // get
        Object.property = x;            // set

    except that C++ requires that methods be used, so ()s must be attached.

    A property is implemented with the following

        Type const & property() const;  // get
        void property(Type const &);    // set -- preferred
        Type & property();              // set -- alternate form

    A method which returns "Type" instead of "Type const &" is creating
    a new object rather than referring to an existing one.  It may be
    a property logically, but in that case it is also possible it is a
    factory method or generator.  Where it fits depends on how you
    perceive it.

    A method which accesses a variable but takes a parameter to do so
    (e.g.

        Type const & method(AnotherType& const token);
    )
    is usually not a property: it could not be represented by an assignment.

    [You may want to learn more by reading about C#s notion of a property,
     since we are attempting to emulate this abstraction:
     http://www.c-sharpcorner.com/Language/PropertiesInCSRVS.asp]

  - Fields:  Any data fields in the object.  Note that fields should be
    private, almost without exception.  Any fields visible outside the
    class should be exposed via properties: fields are implementation
    details.

You may add more sections if you see the need, but try and keep them in
one of the section categories, and note other information after the
category name.  An obvious example are operators, which are methods
but marked as operators, e.g.:

    public: // Methods: Assignment operators

Sections are subdivided by access, with public, protected, and private
subsections in that order.  Some subsections are missing from particular
sections (e.g. there are only private fields).  ALL SECTIONS should
begin with their access level.  Among other things this makes them easy
to scan for automatically.

All sections that are not used can be deleted, and probably should be to
avoid clutter.
