==============================================================================
C-Scene Issue #3
10 Steps to Better C++
Chad Loder
==============================================================================

I have put together some suggestions for beginner to intermediate C++ programmers who want to make their applications more robust and spend less time debugging. Also, there is a big difference between classroom code and production code. I have included some suggestions for people who have not yet made the transition between the code they hand in to professors and real-life working code.

1. Put the constant on the left in a conditional
2. Wrap your header files in #ifdefs
3. Handle errors, not bugs
4. Use asserts in debug builds
5. Use exceptions
6. Don't ignore API function return values
7. Make your code const-correct
8. Comment before you code
9. Be consistent
10. Design a minimal interface

Put the constant on the left in a conditional

while (continue = TRUE)
{
    // ...this loops forever!
}

while (TRUE = continue)
{
    // compile error!
}

Wrap your header files in #ifdefs

#ifndef __MYFILE_H
#define __MYFILE_H

class MyClass
{
....
};

#endif  // __MYFILE_H

Handle errors, not bugs

void CopyString(char* szBuffer, int nBufSize)
{
    if (NULL == szBuffer)
        return;         // quietly fail if NULL pointer
    else
    {
        strncpy(szBuffer, "Hello", nBufSize);
    }
}

void CopyString(char* szBuffer, int nBufSize)
{
    if (NULL == szBuffer)
    {
        cerr << "Error: NULL pointer passed to CopyString" << endl;
    else
    {
        strncpy(szBuffer, "Hello", nBufSize);
    }
}

void CopyString(char* szBuffer, int nBufSize)
{
    assert(szBuffer);   // complains and aborts in debug builds
    strncpy(szBuffer, "Hello", nBufSize);
};

Use asserts in debug builds

void myFunction(char* szFoo)
{
    assert(szFoo);  // same as assert(NULL != szFoo);
}

Use exceptions

class ProgramException
{
    // pass in a pointer to string, make sure string still exists when
    // the PrintError() method is called
    ProgramException(const char* const szErrorMsg = NULL)
    {
        if (NULL == szErrorMsg)
            m_szMsg = "Unspecified error";
        else
            m_szMsg = szErrorMsg;
    };

    void PrintError()
    {
        cerr << m_szMsg << endl;
    };
};

void OpenDataFile(const char* const szFileName)
{
    assert(szFileName);
    if (NULL == fopen(szFileName, "r"))
        throw ProgramException("File not found");
    // ...
}

int main(void)
{
    try
    {
        OpenDataFile("foo.dat");
    }
    catch (ProgramException e)
    {
        e.PrintError();
        return EXIT_FAILURE;
    }
    return EXIT_SUCCESS;
}

Don't ignore API function return values

Make your code const-correct

Comment before you code

Some people tend to restate the code in their comments. Example:

    i++;    // increment i

Many educational style guides suggest that students put large comment blocks above each function. For example, here is a so-called "good" comment block from a style guide I found on the web:

/*------------------------------------------------ COUNT_SEGMENTS -----
     |   Function COUNT_SEGMENTS
     |
     |  Purpose:  COUNT_SEGMENTS computes the number of segments a 
     |  digital clock will need to display the time given by 
     |  the parameters. It then computes the sum of the digits 
     |  and compares the two totals.  If they match, the success 
     |  is recorded by incrementing the sum 'matches' and by 
     |  displaying the time.
     |          The number of segments a digital clock uses to
     |  display any of the ten numbers 0-9 is stored in the array
     |  'segments'.  The array is indexed by the digit; thus, the
     |  number of segments needed to display a '0' is in element [0].
     |
     |  Parameters:
     |  hour1 (IN) - In a two-digit hour value, this is the leftmost
     |      digit.  Ex:  In the time 12:34, hour1 would hold 1.
     |  hour2 (IN) - In a two-digit hour value, this is the rightmost
     |      digit.  Ex:  In the time 12:34, hour2 would hold 2.
     |  tens (IN) - In a two-digit minute value, this is the leftmost
     |      digit.  Ex:  In the time 12:34, tens would hold 3.
     |  ones (IN) - In a two-digit minute value, this is the rightmost
     |      digit.  Ex:  In the time 12:34, ones would hold 4.
     |  matches (IN/OUT) - The sum of the times the number of segments
     |      equals the sum of the digits.
     |
     |  Returns:  Nothing.  (This is a void function.)
     |
     *-------------------------------------------------------------------*/

void count_segments (int hour1, int hour2, int tens, int ones, int *matches)
{
    // function body...
}

Be consistent

Design a minimal interface

// integer data container, I have provided every conceivable way of setting the data
class MyClass
{
    // set data from integer
    void SetData(int n);

    // set data from character representation of decimal integer
    void SetData(const char* szDataString);

    // set data from character representation of hex integer
    void SetDataHex(const char* szDataString);

    // set data from double, round it up to nearest int
    void SetDataUp(double d);

    // set data from double, round it down to nearest int
    void SetDataDown(double d);

    // set data from double, floor the double
    void SetDataFloor(double d);

    // set data from user input from stdin
    void SetDataInput();

    // set data from file
    void SetDataFile(const char* szFileName, unsigned long ulOffset);
};