CS 132 Basic Opening-Comment Block Templates
Version 1.1, last modified: 1-26-05

for functions:

//---------------------------------------------------------------------
// File:
// Name:
// last modified:
//
// Contract:
//
// Purpose:
//
// preconditions:
//
// postconditions:
//
// Examples:
//
// libraries/other functions used:
//---------------------------------------------------------------------


for header files:

// Header file for function: x
// Name:
// last modified:

#ifndef X_H
#define X_H

// header file contents

#endif


for basic testing main's:

//---------------------------------------------------------------
// File: test_X.cpp
// Name:
// last modified:
//
// Purpose: tester for function X
//--------------------------------------------------------------

#include <iostream>
#include "X.h"
using namespace std;

int main()
{
    // set-up declarations

    // tests and associated cout's

    cout << endl;
    cout << "Testing function X..." << endl;
    cout << endl;

    cout << "1's mean test passed, 0's mean test failed:" << endl;
    cout << "-------------------------------------------" << endl;
    //or:
    cout << endl;
    cout << "should see <X>: <";
    X(X);
    cout << ">" << endl; 

    return EXIT_SUCCESS;
}


for a method within a class:

// method: x
//
// preconditions: [IF needed ]
//
// postconditions:
//
// Examples: [NOT needed for BASIC 
//    constructors/accessors/observers/modifiers. Otherwise, needed.
//
// Library facilities used: [IF needed ]


HEADER file for a class:

//---------------------------------------------------------------------
// File: x.h
// Name:
// last modified:
//
// Class name: x
//
// Description:
//
//---------------------------------------------------------------------

#ifndef X_H
#define X_H

class x
{
    public:
        /****************************************************/
        /* TYPEDEFS and MEMBER CONSTANTS                    */
        /****************************************************/

        // put declarations of typedefs and member constants here; precede
        //    each with a descriptive comment unless it is REALLY obvious

        /*****************************************************/
        /* CONSTRUCTORS and DESTRUCTOR                       */
        /*****************************************************/

        // put declarations for constructors and (if needed) destructor here;     
        //    additional "opening" comments are only necessary if a 
        //    constructor's usage is not obvious (for example, a postcondition 
        //    indicating default data fields' resulting values)

        /*************************************************************/
        /* ACCESSORS and other constant member functions (observers) */
        /*************************************************************/

        // put declarations for accessors here; additional 
        //     "opening" comments are only necessary if an accessor's usage 
        //     is not obvious (for these, often only a postcondition is
        //     needed, if any additional comment is needed at all)

        /*****************************************************/
        /* MODIFIERS and other modifying member functions    */
        /*****************************************************/

        // put declarations for modifiers here; additional 
        //     "opening" comments are only necessary if a modifier's usage 
        //     is not obvious (for these, often only a postcondition is
        //     needed, if any additional comment is needed at all)

        /*****************************************************/
        /* OVERLOADED PUBLIC MEMBER FUNCTIONS and OPERATORS  */
        /*****************************************************/

        // put overloaded public member function declarations here; 
        //    each should have a method opening comment block (see template)

        /*****************************************************/
        /* OTHER PUBLIC MEMBER FUNCTIONS                     */
        /*****************************************************/

        // put other public member function declarations here; 
        //     each should have a method opening comment block (see template)

    private:

        /*****************************************************/
        /* DATA FIELDS                                       */
        /*****************************************************/

        // declare data fields here. Put comments to the side of any 
        //    that need explanation (are not obvious)

        /*****************************************************/
        /* PRIVATE MEMBER FUNCTIONS                          */
        /*****************************************************/

        // put private member function declarations here; each should have a
        //     method opening comment block (see template)
};

/*************************************************/
/* NONMEMBER FUNCTIONS for the x class           */
/*************************************************/

// put non-member function declarations for the class here; each should have a 
//     method opening comment block (which should be copied from x.h)

#endif


IMPLEMENTATION file for a class:

//---------------------------------------------------------------------
// File: x.cpp
// Name:
// last modified:
//
// Class name: x
//
// Purpose: (can be copied from x.h)
// 
// Implementation notes: (these will go here, and NOT in the x.h opening
//     comment block)
//---------------------------------------------------------------------

#include <cassert>
#include "x.h"
using namespace std;

/*****************************************************/
/* CONSTRUCTORS and DESTRUCTOR                       */
/*****************************************************/

// put implementations for constructors here; additional
//    "opening" comments are only necessary if a constructor's usage
//    is not obvious (in this case, they can be copied from x.h)

/*************************************************************/
/* ACCESSORS and other constant member functions (observers) */
/*************************************************************/

// put implementations for accessors here; additional 
//     "opening" comments are only necessary if an accessor's usage 
//     is not obvious (in this case, they can be copied from x.h)

/*****************************************************/
/* MODIFIERS and other modifying member functions    */
/*****************************************************/

// put implementations for modifiers here; additional 
//     "opening" comments are only necessary if a modifier's usage 
//     is not obvious (in this case, they can be copied from x.h)

/*****************************************************/
/* OVERLOADED PUBLIC MEMBER FUNCTIONS and OPERATORS  */
/*****************************************************/

// put overloaded public member function implementations here; each should have
//    a method opening comment block (which can be copied from x.h)

/*****************************************************/
/* OTHER PUBLIC MEMBER FUNCTIONS                     */
/*****************************************************/

// put other public member function implementations here; each should have a
//     method opening comment block (which can be copied from x.h)

/*****************************************************/
/* PRIVATE MEMBER FUNCTIONS                          */
/*****************************************************/

// put private member function implementations here; each should have a
//     method opening comment block (which can be copied from x.h)

/*************************************************/
/* NONMEMBER FUNCTIONS for the x class           */
/*************************************************/
       
// put non-member functions for the class here; each should have a 
//     method opening comment block (which should be copied from x.h)


for a testing main for a class:

//---------------------------------------------------------------
// File: test_x.cpp
// Name:
// last modified:
//
// Purpose: tester for class x
//--------------------------------------------------------------

#include <iostream>
#include "x.h"
using namespace std;

int main()
{
    // declarations
    // declare class instances (and anything else needed for tests),
    // (including calling each constructor at least once)

    cout << endl;
    cout << "Testing class x..." << endl;
    cout << endl;
    
    // verify the constructors and test the accessors/observers 
    //    at the same time
    cout << "VERIFYING CONSTRUCTORS/ACCESSORS/OBSERVERS:" << endl;
    cout << endl;
    cout << "1's mean test passed, 0's mean test failed:" << endl;
    cout << "-------------------------------------------" << endl;
    
    // accessor/observer calls and associated comparisons and cout's

    // verifying the modifiers

    cout << endl;
    cout << "VERIFYING MODIFIERS:" << endl;
    cout << endl;
    cout << "1's mean test passed, 0's mean test failed:" << endl;
    cout << "-------------------------------------------" << endl;

    // modifier calls and associated comparisons and cout's

    // other methods/operators tests -- can use same basic approach as
    //    for functions, except they can be included in this same
    //    testing function.

    return EXIT_SUCCESS;
}