General Hints, Tips and Tricks for C++

This page provides hints, tips and tricks which may prove useful when solving the exercises of the C/C++ course. Use them to your advantage. The bracketed names given with the hints refer to the set of exercises from where the hint can/should be applied.

New hints may be added to the various sections while the course is running. In those cases: newly added hints are flagged by a

-image

Hints WRT Part I

Intro

Use a fairly recent compiler. The oldest version that can still be used is mentioned with the exercises for the introductory lecture.
Use -Wall for all compilations. Make sure your code compiles free of warnings.
Specify the ---std=c++26 standard.
Use streams for all input and output: use cout for insertions into the standard output stream, use cin for extractions from the standard input stream. Do not use the C print and scan family of functions.
The extraction operator (i.e., >>) by default skips leading whitespace. If a string is extracted, all initial whitespace is skipped as well.
White space not only consists of blanks and tabs, but also of newlines.
Use (and define) enums or enum class-types and values, rather than int constants in cases where your values aren't used as numeric values but to indicate categories.
With categories there are usually no compelling reasons to associate the category names with specific numeric values. Therefore resist the temptation to assign values to enum-names unless there are good reasons (e.g. when using bitflags) for doing so.
The initial letter of self-defined types should be Capitalized, to make a clear distinction between self-defined types and variables. An enum-name is a self-defined type. Use (also to indicate their nature) CAPITAL LETTERS for symbolic enum constants.
As a suggestion: rather than using underlines, prefer camelCase: capitalize the different words that you use when defining type- or variable names. E.g., use errorCount rather than error_count.
Raw string literals break your layout if you include them in your function bodies. Don't do that. Instead, define the raw string literal near the top of your source file as a char const name[] array (where `name' is an appropriately chosen name, describing the nature of the raw string literal), and use that name in, e.g., cout statements inside function bodies. Preferably define the variable inside an anonymous name space. Example:
```
    #include <iostream>

    namespace {                 // anonymous name space

    char const hello[] =        // define the Raw String Literal
    R"(
    ***********
    hello world
    ***********
    )";

    }   // namespace ends

    int main()
    {
        std::cout << hello;     // display the Raw String Literal
    }
        
```
Very soon, especially when you have some previous experience in using C/C++ you'll encounter exercises that you can solve using your knowledge of the language by resorting to more advanced constructions than we've covered so far. Suppress the desire to do so. Like becoming a good carpenter first learn to use the plain tools like saw and chisel before using power tools like routers and lathes. Always try to solve exercises using the topics covered so far, unless there is an explicit suggestion to do otherwise. Don't jump ahead!
Suppress the desire to look up things using google or chatGPT. Both often do fine, but in this course we're not going for the quick fixes. Instead, first study the relevant sections(s) of the Annotations (with each lecture sections of the Annotations (and sometimes the C book) are provided as reading suggestions); then, when you know what it's all about start solving the exercises.
When defining variables avoid definition lists, like
```
    string name, lastname, address;
        
```
Instead define each variable on a line of its own:
```
    string name;
    string lastname;
    string address;
        
```
The reason for this is that it makes it easy to relocate definitions (you should always localize variables definitions as much as possible), and you'll immediately see what their initial values are.
When programs expect input then you may assume that the input is correctly formatted. In your exercise you don't have to check that unless the exercise explicitly asks you to do so. Validating input is a very good habit, which you should do in real life, but in the exercises it quickly distracts from the exercise's purpose.
When using code in verbal explanations or textual answers make sure that there too you adhere to the code hints and tips, and to the layout conventions (see also the common layout violations as described in the abbreviations).
When answering exercises always be concise. Just answer the question and don't provide verbose stories.

About using comment:

Comment is used to add brief explanations to statements. `Brief' means: not long and verbose. As a rule of thumb: use at most 40 characters when adding comment to statements.
Comment should not reformulate what's already available in the statement itself. Rather, comment should be semantic: what's the purpose of the statement. Here is an example of a statement you might encounter in a C++ source file. It is shown twice. The first time it is provided with useful comment, the second time it is provided with useless comment. Only use the former type of comment in your code:
```
    offset = tmp.tellp();           // offset of the 1st entity
        
```
avoid this type of comment:
```
    offset = tmp.tellp();           // offset hold tmp's current offset
        
```
The latter type of comment should be avoided because it basically repeats the statement itself. Instead, the former type of comment tells the reader something about that particular offset location. That's why it's called a semantic comment.

Also notice the layout of the comment: try to align comments in a source file in such a way that the comments are neatly ordered underneath each other. Sometimes the statement is too long. In that case put the comment just above the statement. Here's an example:


                            // a generic object copy, owned by uid, and
    if                      // initially copied by uid
    (
        obj.genID() != maxUint16 and obj.ofUser(uid) and 
        obj.orgID() == uid
    )
        ...

Longer, descriptive comments about what a function is doing traditionally is preceding the code. It turns out that that's not the optimal position of such comment. In practically all situations the function's implementation is what a software engineer is interested in, and only when the design considerations are an issue the longer, descriptive comment is inspected. Therefore long, descriptive comments should be provided after providing the C++ code itself (in very much existing code the longer, descriptive comments still precedes the C++ code: in due time this will change to this new layout). Here is an example (merely consider the organization, not the meaning: the C++ code precedes the descriptive comment):
```
int Parser::local(string &ident, int value)
{
    d_symtab.local(ident);
        
    return value;
}

// The name of the variable is stored in the symbol table in a vector of
// names. The initial value is stored in an Int32Vector, using the
// variable's value at the corresponding index position.
// When the variable is subsequently used, its index is obtained, allowing
// for instructions like 'push var 3'. Since the variable array of that
// state also has at least that many elements the value can be retrieved
// and saved.
    
```
In situations where your (main- or other function) has an empty body, the function body's curlies can be written next to each other. The following implementations are therefore equivalent and accepted:
```
    int main()
    {}
    -------------
    int main()
    {
    }
        
```
Closing curlies of compund statements should be written on a line by themselves (but may optionally be followed by comment).

Finally, empty lines also are an extremely useful tool for organizing code. Statements are commonly organized in (short) series accomplishing a certain task. Subsequent and earlier statements serve other purposes. Separate such sets from each other by empty lines:


void execute(Uint8Vector const &code, bool showObjects)
{
    if (code.size() == 0)               // leave if there's no code to exec.
        return;

    d_ip = &code.front();               // begin at the 1st opcode

    while (s_opcode[*d_ip++]())         // execute the instructions in 'code'
        ;
}

Expressions

An expression statement (and below: flow control statements) are statements. A variable or object definition is not commonly considered a statement.
When defining variables define every variable on a line by itself, using its own type specification. Advantages: it is easy to move your variable to another point in the source file to improve localization, and it's easy to add a short semantic comment behind the variable definition.
By default, the char-type has signed values. This may result in unexpected program behavior if a char variable is used as an array-index. In order to prevent this from happening, avoid char variables except for true character input/output. When a character must be read with the intention to use its value as an array-index, take one of the following approaches:
- int istream::get() (e.g., cin.get()), returns an int, which is positive except at end-of-file, when the predefined constant EOF is returned. This return value can be assigned to an int variable, which can thereupon be used in, e.g., index expressions.
  When assigning the return value to a char realize that the char may be negative, and should thus not be used in index expressions.
- Cast a signed character variable before assigning its value to an unsigned type. Although a char may directly be assigned to an unsigned char or to an uint8_t, defined in cstddef. This effectively maps the range -128 .. -1 to 128 .. 255. E.g., static_cast<unsigned char>(char-expression). The header cstddef is often already included by other standard headers (like iostream) in which case you do not have to include it explicitly.
- [Deprecated (so don't do this!! ...)] Change the default interpretation of the char type, using a compiler flag. If the flag -funsigned-char is provided the char type will be interpreted as an unsigned type.
Try to use existing functions. Consult man-pages. The man-pages of all suggested functions are provided on the course's <a href="/edu/1/manpages">man-pages page</a>. Do not bluntly apply a listed function. Sometimes they are there for reference purposes only. For example: rules of thumb like `use std::string objects where possible' deprecate certain functions (in particular str...() functions) see below.
NTBSs are not C++-strings. If a function expects an NTBS argument convert a C++-string to an NTBS first using the string's c_str member.
Raw String Literals are also NTBSs.
The functionality of many legacy C-string functions (like strlen) are better provided by C++-string objects. Don't use the C str... legacy functions when the C++ strings can be used as well. E.g.:
```
    // assume c_string is a NTBS, cpp_string is a C++ string

    strlen(c_string);       // don't use this
    cpp_string.length();    // use this instead
        
```
Know why you use the string's at member function. If you do so because Java offers the at member function then learn about the index operator ([]). Whenever you're convinced that the index does not or cannot exceed the string's index-bounds, use the index-operator []: it's more efficient. When a pointer to a string (introduced later during part I) is available, first dereference the pointer, then use [] (e.g., prefer (*str)[idx] over str->at(idx), let alone str->operator[](index)).
Prefer prefix increment over postscript increment (and decrement, of course).
Start names of variables (and later: objects) with lower case letters. Read also the hints about what letter casings to use for self-defined types in the intro hints and tips.
C++ programs should not use #define compiler directives, except for defining include guards, which are covered in the lecture about functions (in part III we encounter another (local) use of the #define directive).
Take care of the layout of exercises that you submit: they will be interpreted as C++ code as received on paper. Therefore, prevent lines being wrapped around by your printer. E.g., a long cout statement might be printed like:
```
    cout << "Let's assume that this is printed by your printer, but the line
is too long, and so the printer `wraps around'\n";
        
```
This is interpreted by us as two lines of source code, which
- Violates the layout rules and:
- Won't compile
If you have a long line, split it over multiple lines, ensuring a readable layout. E.g.,
```
    cout << "Let's assume that this is printed by your printer, "
            "but the line is too long, and so the printer `wraps around'\n";
        
```
The above example illustrates string concatenation, which is supported by the language and avoids an additional cout statement or insertion operator. In general,
- prefer repeated insertion operators over series of cout statements.
- End lines containing multiple expressions inserted into cout with an insertion operator or a semicolon. Use string concatenation if a series of C-strings are inserted (as in the above example).
Here is an example of a long cout statement illustrating the preferred layout:
```
    cout << "Let's assume that this is printing " << aValue << "\n"
            "using string concatenation\n"
            "Start a new line following \\n, insert " << multiple <<
                variables << likeThis << '\n';
        
```
Some minor layout points deserving your attention:
- Put a blank behind a comma. After all you do that in natural languages too.
- Casts represent one operation, Do not put blanks inside casts. Examples (here using a single letter variable: avoid in your code):
```
    static_cast<size_t>(x)      // OK

    static_cast<size_t> (x)     // don't
    static_cast <size_t>(x)     // don't
    static_cast <size_t> (x)    // don't
        
```
Avoid inserting std::endl into streams unless you're really intending to flush the stream. Streams are automatically flushed when they go out of scope (and with std::cout: when the program ends and also when the next statement involves std::cin).
When inserting single characters into a stream, do not use the double quoted C string but use a character constant (between single quotes). So, rather than:
```
    cout << "\n";
        
```
use:
```
    cout << '\n';
        
```
An NTBS (double quotes) tells the stream object to insert all characters until a final 0-byte is encountered; a character constant tells the stream object that exactly one character should be inserted and thus is more efficient.
If a single character is immediately followed by the insertion of additional textual characters then use string concatenation: in that case use double quotes for the single character but omit the next insertion operator. E.g.:
```
    cout << whatever << "\n"
        "string concatenation. The previous \\n is merged with this text\n";
        
```
Prefer size_t types over int when only non-negative integral values are used. See the Annotations for details.
A static_cast operation is not required when assigning values of comparable data types but different sizes. Assigning an int to a char and v.v. can be performed without a static_cast. A static_cast is appropriate to change the `signed' quality of a type or to cast a value to a `wider' type in a non-default way. A good example of the latter use is casting an int variable in an int expression to a double if the resulting exxpression should be of double type. Casting the full expression is pointless, as the compiler will first evaluate the expression (as an int) and then convert the result to double, which basically doesn't do anything at all.
Using floor to remove the fraction of a double before assigning its value to an int is pointless: the default assignment process already ignores the fraction.
Avoid using `small types' like char or short unless the context requires their use. With char that's always a situation where characters are to be displayed, short is only required in very specific cases (and even then, (u)int16_t is probably preferable). Therefore, use short only when you're required (as in: forced) to use it.

Flow

Put a blank after keywords. Do not normally put a blank after an open-parenthesis and before a closing parenthesis if they are part of the statement syntax. E.g.,
```
    if (x == y)     // not: if( x == y )
                    // not: if(x == y) 
                    // not: if ( x == y ) 
        
```
Blanks in parenthesized expressions are OK if the expression is complex and itself contains sub-expressions that are parenthesized.
In the abbreviations file two entries relate to the use of comment. Comment in the source code should not be too verbose, since this distracts from the code itself. Put verbose comment at the top of your sourcefile.
Comment within your code (within functions) should use end-of-line (eoln) comment. But again: don't put the comment at the same level of the code, because that makes it hard to distinguish at first glance code and comment.
Eoln comment should be concise and must provide additional information about the statement beyond what the statement already offers. E.g., this is CC:
```
    string str;         // define str
        
```
Cluttering comment should be omitted. There really is no need to provide comment to self-explanatory lines in your sources.
This example's comment, however, isn't CC:
```
                        // process all command-line arguments
    for (size_t idx = 1; idx != arc ++idx)
        
```
Wrt comment layout, to distinguish comment from code use the following rules:
- Eoln comment should be placed behind the statement, all eoln comments preferably starting at the same column position (a good location is half-way the width of your source file). Example:
```
    nCombinations = 1 << argc;          // compute 2**argc: # combinations
        
```
- If a statement is too wide, put the comment immediately above it, obeying the indentation rules. Example:
```
                        // process all command-line arguments
    for (size_t idx = 1; idx != argc; ++idx)
        
```
- Eoln-comment must be semantic. The comment shown above are examples of semantic comment. Comment like
```
                        // idx iterates from 1 to argc
    for (size_t idx = 1; idx != argc; ++idx)
        
```
  provides no additional information, and we call that cluttering comment, lowering your exercises' ratings
- Add a blank line between lines in your function(s) performing semantically different parts of its task. E.g.,
```
    int main(int argc, char *argv[])
    {
        .....       // inspecting the arguments
        .....

        .....       // processing arguments
        .....
        .....

        .....       // performing the program's core business
        .....
    }
        
```
In an if or if-else construction, do not use curlies around single nested statements, but only if the nested statements themselves contain multiple statements. Avoid constructions like:
```
    if (argc == 1)
    {
        usage(argv[0]);
    }
    else
    {
        process(argc, argv);
    }
        
```
Within the world of C++ this is a dialect that belongs to another language (e.g., Perl).

If an if-statement defines a variable that's only used in the if-statement, followed by the actual condition to be tested, then use an extra blank after the semicolon, or split the two elements over two lines. E.g.,


    if (double value = assign();  -1e-8 <= value and value <= 1e-8) 
        ...

or:


    if 
    (
        double value = assign();  
        -1e-8 <= value and value <= 1e-8
    ) 
        ...

In an if-else construction, try to write the shorter nested statements first, and put the longer statement in the else substatement, especially if the if-true statement is a compound statement. This holds especially true for constructions like:
```
    ...
    else
        break;
        
```
By the time you reach the else, you've probably forgotten what the condition was all about. Furthermore, changing substatements may actually make the if-else superfluous as execution terminates at the break. So, rather than
```
    if (condition)
    {
        // relatively much code
    }
    else
        break;
        
```
use:
```
    if (not condition)
        break;

    //relatively much code
        
```

In a series of connected if-else statements (an if-else ladder), write the if following an else immediately after the else, and do not additionally indent:


    if (cond-1)
        statement-1;
    else if (cond-2)
        statement-2;
    else if (cond-3)
        statement-3
    else
        statement-4

An if-else construction where the same variable receives a value in both conditions, should be rewritten using the ternary operator (and by implication: this holds true for comparable other situations as well, e.g., return statements). Example:
```
    // don't:
    if (condition)
        x = value_1;
    else
        x = value_2;

    // do:
    x = condition ? value_1 : value_2;
        
```
It's less work, describes concisely what you intend, it's applicable within expressions, and possibly allows the compiler to apply more direct optimizations and in an if-else statement, which, after all, contains three `statement' parts.

In an if-else construction, avoid else following a sub-statement terminating in break, return, exit or throw (covered later):


    if (condition)
    {
        ...
        return;
    }
    else        // the else and subsequent compound stmnt are not required
    {
        stmnt 1
        stmnt 2
        ...
    }

Instead, use:


    if (condition)
    {
        ...
        return;
    }
    stmnt 1
    stmnt 2

Prefer a switch over an if-else ladder: it's faster and easier to understand and maintain.
The basic form for defining an incremental for statement (from 0 to n) is:
```
    for (size_t idx = 0; idx != end; ++idx)
        
```
The basic form for defining a decremental for statement (from end to 0) is:
```
    for (size_t idx = end; idx--; )
        
```
Reserve the for statement for situations where you know in advance how many iterations to perform; use the while statements for an undetermined number of iterations.

The basic form for reading C/C++ streams (i.e., files) is as follows:


    while (true)
    {
        optionally perform tasks before reading information

        read information

        if the reading fails (e.g., end of file was reached)
            break;

        process the obtained information.
    }

Contractions are often possible, in particular when no repeated pre-processing is required (i.e., there is no task to perform before information is read):


    while (getline(cin, string))
        process the read information.

or:


    while (cin >> variable)
        process the read information.

Whenever the number of iterations is known, use a for statement. Whenever the number of iterations is unknown, use a while statement. This is the distinguishing characteristic of these two statements, and respecting this distinction helps you or others to understand your code.

With for statements use the canonical forms. Using the canonical forms avoids the notorious `off-by-one' error and automatically takes you into the `world of offsets' which is almost always the world in which for statements are used:



    // IdxType: the index type that is used

    for (IdxType idx = 0; idx != end; ++idx)       // proceeding upwards

    for (IdxType idx = end; idx-- != begin; )      // proceeding downwards

    for (size_t idx = end; idx--; )                // (same, numeric IdxType)

If you use and array or other data structure of know size (many are introduced later on) and want to process each element in turn, consider using the range-based for-loop. See the Annotations for details.
Although you should localize, sometimes you can slightly relax that requirement. In particular when you need a constant value inside a loop the compiler will recompute that constant value every time you enter that loop. In that case put the constant value just outside of the loop. Example:
```
    ...
    string const text = "constant text";
    for (size_t idx = 0; idx != 5; ++idx)
        cout << text << '\n';
    ...
        
```
But also note that the range-based for-loop has an optional initial variable initialization section (see the slides)
If the final or only statement in a while statement is an if-else statement, consider leaving out the else, ending the first substatement in continue: it allows you to omit the indentation of the else substatement. Since the else substatement usually is the longer substatement it tends to produce code that is easier to read.

In while statements prevent the famous Pascal statement flaw, which is another example of a dialect. Usually the perpetual loop is the construction to apply:


    // Avoid the Pascal-like statement repetition:

    prompting();
    while (obtainData())
    {
        processData();
        prompting();            // statement repetition
    }

    // Instead use a continuous loop:
    
    while (true)
    {
        prompting();
        if (not obtainData())
            break;
        processData();
    }

)

Generally avoid do-while statements. They are seldom required. If you think you need them you're probably wrong. In this course its not prohibited to use do-while statements, but your solution is downgraded if you use them without real necessity.
When processing the information read from files (currently it's just cin), do not use the Perl-idiom of reading the file's full content in a string variable, followed by processing the string. This may work for relatively short files, but for longer files it's a definite no-no, as you'll easily exceed the string variable's storage capacity.
Instead carefully read the exercise's text and adopt its `unit of analysis': if the exercise is about character processing, process characters; if the exercise is about line processing, process lines; if the exercise uses another `unit of analysis', use that.
Using idioms from other languages might be OK, but often is signals lack of mastery, and we'll consider it C++-dialect, which downgrades the ratings you receive.
When reading from cin (usually a full line using getline(cin, line) or extracting the next entry using cin >> destination), cin itself can be used to check whether the extraction succeeded (as in if (getline(cin, line)) or if (cin >> destination) or even if (cin)). Before using the 3rd form you have to make sure that you first have tried to read something from cin.

Functions

Layout: do not put a blank between function names and their parameter lists or argument lists; do not put a blank after the opening parenthesis and before the closing parenthesis of a parameter- or argument list. Example:
```
    void functionName(int param1, int param2)
        
```
(some keywords, like if, switch, for and while, are followed by open parentheses. A blank is inserted between those keywords and the open parentheses following them).

Programs should have a function

void usage(string const
        &programName)

(or char const *programName) displaying usage information and terminating the program. This function is called when no (or maybe: too few) arguments are passed to the program.

Notes: Your usage information should make sense, and should provide a to-the-point summary of how to use your program (and maybe a single line stating its purpose). Don't be frivolous here. Here is an example of how what usage info may look like:


cidr by Frank B. Brokken (f.b.brokken@rug.nl)
cidr V1.20.01 2006-2013

Usage: cidr [options] cidr-file
Usage: cidr [options] cidrpattern line
Where:
   [options] - optional arguments (short options between parentheses):
      --help (-h)      - provide this help
      --quiet (-q)     - don't output the matching cidr if found
      --verbose (-V)   - give a verbose report of what's going on
      --version (-v)   - show version information and terminate
   cidr-file - file containing cidr-patterns, one per line.
               cidr returns 0 if a line on stdin contains
               an IP4 address matching a cidr-pattern, and 1 otherwise.
   cidrpattern line: inspect line for an ip-address matching cidrpattern
               returns 0 if so, 1 if not

When constructing a program for which you defined multiple functions in separate files, then make sure that
- you define only one header file in which all your functions are declared. In this header file do not declare main;
- don't define a separate header file for each individual function;
- your function declarations are identical to their definitions, replacing functions' bodies by semicolons. In function declarations (and not in function definitions) default arguments may be specified for the parameters.
Since your header file is only used by the sources of your program (rather than declaring the functions of a software library) we consider such header files internal header files, and prefer the extension .ih rather than .h.

Here is an example of the basic setup of such a header file:


#include <iostream>
#include <string>
// other header files may be required as well. Include them here.

void usage(char const *programName);    // all declarations of functions we
...                                     // developed ourselves for this
...                                     // program, preferably alphabetically
...                                     // ordered by function name

// optionally, as we're the only ones using this header file:
using namespace std;            // and/or any other namespace you use.

When we're constructing a program demo all sources of the demo program may now start with:


    #include "demo.ih"

    // followed by a function definition ...

Although main can define an int argc parameter, that's a legacy. We know that argc is positive and at least 1. Often argc needs to be passed to functions processing command line arguments, and often a for statement is used for that. In those cases simply define a size_t argc parameter for such functions, and pass it main's argc. You can safely do that because
- you know that argc > 0;
- conversions from int to size_t are automatically performed: using a cast is not necessary
So, if your function is showArgs(size_t argc, char *argv[]) you can simply do:
```
    int main(int argc, char *argv[])
    {
        ... // whatever
        showArgs(argc, argv);
        ... // whatever
    }
```
and define:
```
    void showArgs(size_t argc, char *argv[])
    {
        for (size_t idx = 1; idx != argc; ++idx)    // canonical for loop
            cout << "argument " << idx << " is: " << argv[idx] << '\n';
    }
```
When you're constructing a function and you feel the need for additional (auxiliary) functions, then feel free to define such functions. If these functions are not part of another exercise, but are the result of your own program-development process, then submit the sources of these auxiliary functions together with the source of the requested function.
When declaring functions provide the same names to their parameters as used in the function definitions. This improves the readability of the declarations because the parameter names suggests what they are used for.

Here is an overview of various types of parameter definitions (exceptions exist, but they will only appear in the context of part III of this course):


    ------------------------------------------------------------------------
    value:
        primitive types:    e.g., (int counter)
                            Don't use const, since the parameter's scope  is 
                            restricted to the function anyway.

        class types:        Generally: AVOID
                            Avoid class type value parameters: 
                            they require a full object copy which sometimes is
                            downright impossible.
                            USE a value class type parameter when it is used
                            as a working object which would otherwise have
                            been defined as a local object initialized by the
                            parameter.

    const reference:        
        primitive types:    AVOID
                            Avoid this. Use value parameters instead:
                            parameter passing is easier and value
                            parameters are handled more efficiently.

        class types:        e.g., (std::string const &message) 
                            Use this when you only access the information of
                            the parameter. In this case never use a value
                            parameter instead.

    non-const reference:
        primitive types:    e.g., (int &nSuccesses)
                            AVOID this. 
                            It is acceptable to use this form to implement 
                            `return by argument' until we have covered 
                            pointers. By convention return by argument
                            parameters are defined before other parameters.

        class types:        e.g., (std::istream &in) 
                           Used to communicate the existence of objects living
                            outside of the function to the function. Such
                            objects are used, and may be modified. `Return by
                            argument' constructions are primarily used to
                            assign new values to the objects/variables
                            referred to by the `return by argument'
                            parameters. It is acceptable to use non-const
                            references to implement `return by argument' until
                            we have covered pointers.

        r-value references: e.g., (std::string &&tmp)

                            Used when the current function may swallow (some
                            say: steal) tmp's data. Following the call of this
                            function tmp should cease to exist. Rvalue
                            references are primarily used to implement
                            so-called `move constructors' which are introduced
                            at the earliest by the end of part I.

    pointers to const entities:
        primitive types:    e.g., (char const *message) Used when the `natural
                            type' is a pointer, like an NTBS. Here the
                            parameter is an input parameter.

        class types:        e.g., (std::string const *msgPtr)
                            Generally not used. Instead const references are
                            preferred. 

    pointers to non-const entities:
        primitive types:    e.g., (int *successPtr)
                            Used for `return by argument' constructions. To be
                            defined before any other kind of parameters
        class types:        e.g., (std::string *textPtr)
                            Same.
    --------------------------------------------------------------------------

To return types comparable considerations apply. Make sure that returned references refer to and that returned pointers point to something that remains in existence after the function has terminated. 0-pointers are an exception to this rule. Primitive type and class type value return types are both commonly used.
Normally avoid class type return values unless the function is a factory function, returning an object created by the function. Rvalue reference return types have have very limited use: do not define them unless exercises explicitly tell you to do so.
Consider using structured binding declarations when your function returns POD with fields of various types.
Functions should not be too large and should not contain deeply nested statements. A function's body should not exceed approx. 25 lines. Define support (auxiliary) functions handling parts of a function's task or a function's nested code.
Make it a habit to define one function in one file, where the filename mimicks the function name. The advantages of this style are
- If a function needs maintenance it's easy to find it, since the file name resembles the function's name. I (F) don't use capitals and no underscores in filenames, because in the end they complicate finding the correct filename. But if you like capitals and underscores: go ahead.
- Following maintenance the source file compiles faster than a file also containing many other function definitions
- Finding the function needing maintenance is more difficult if it is defined in a source file containing many other function definitions
- Sometimes function overloading results in multiple functions having identical names. In those cases number the files, and specify in the header which overloaded function received which number. E.g.,
```
void process(std::string const &arg);   // process all lines  1.cc
                                        // process one line   2.cc
void process(std::string const &line, std::string const &arg);   
        
```

Classes

Adopt our naming conventions: start data members with d_. Class names, like all your self-defined types, start with a Capital letter.
Constructors initialize data members, thus validating the object for being used. They do not perform other tasks. It is the responsibity of other (maybe public) members to perform additional tasks.
If a constant initialization expression is used (i.e., an expression not referring to variables or functions) then data members can also be initialized in the class headers. However, prefer constructor initializations since altering the initializations then only requires you to recompile that constructor instead of reompiling all sources implicitly using initialized value from the class header. Constructor initializations always overrule header initializations.
All member functions that can be const member functions, must be const member functions.
Make sure you understand how to define return types. Reread the functions HAT if you think you should return, e.g. int const values from members or if you think you should define, e.g., bool const & parameters. Defining bool const parameters is OK if you want to stress that you're not going to change the parameter's value in your function.
Objects that are used by multiple objects are usually passed as (maybe modifiable) references, initializing reference data members. Never copy such objects. Sometimes that's plain impossible, but, more importantly, by copying you break the shared nature of such objects.
Often header files include other header files. Therefore, by including, e.g., <iostream> you may also implicitly have included <string>. Never rely on this relationship between headers: it's an `undocumented feature' at best, which may not be supported anymore by newer versions of your compiler. Instead,
- If a class header or definition requires a type X, make sure the appropriate X header file is included before your class header or definition starts.
- With C structs, (like tm), consult the man-page to find the appropriate header file (in this case time.h or ctime).
In many cases self-defined class header files do not actually have to include other header files when referring to objects of classes defined by those headers. Headers must only be included when your class interface defines data members of types mentioned in such headers or when using member functions or subtypes (e.g., enumeration types) specified by those headers. Otherwise mere class declarations suffice.
To merely declare any std stream type or the type std::string include iosfwd.
When implementing class member functions returning a value of an enumeration type (defined by the class) the class scope must also be provided when defining the return type. So, if a class MyClass defines an enum Type and declares a member Type type() const, then type's implementation looks like this:
```
    MyClass::Type MyClass::type() const
    {
        ....
    }
        
```
Since the enum is now firmly attached to the class name, this usually also obviates the use of a strongly typed enum.
When an enumeration has values describing the behavior of a class, and it isn't already defined elsewhere, define the enumeration within the class. In that case, if the enumeration's values must be visible outside of the class's scope and if you want a data member of the enumeration's type, then consider defining the class as a struct, and immediately below the class's opening brace define all publicly visible types and enums, followed by a private section for the data.
Otherwise, types and enumerations that are used for the class's own benefit should be put in the first available private section.
When implementing private members, keep these members as simple as possible. Since their calling is completely at the control of your class's members, strong assumptions about their arguments may at times be made (e.g., valid values, values in a certain range, etc.). In these cases no checks are required to ascertain the validity of these assumptions in the private members themselves. In contrast, public members should check the validity of received argument values before actually using them. If the checking code can be factorized, then do so. In that case, create additional private functions for these purposes.
Adopt the convention of creating a driver program (e.g., in a subdirectory of the class directory itself) showing the proper functioning of the (public) members of the class. Such a driver can be developed in parallel with the development of the members of a class: construct a member, add its use to the driver, show to yourself that the driver works properly. Its good practice to show/test a member's behavior for both correct and incorrect input.
Adopt the conventions suggested by Trolltech, the creators of the Qt library: accessors should not be given names starting with get.... Eg, use
size()
rather than:
getSize()
.

Often, set members can be defined likewise: overloaded functions usually do the trick. Instead of


    setInt(int x);
    setDouble(double x);

define:


    set(int x);
    set(double x);

Declare private member functions below the public member functions. Contrary to this, data members should be positioned at the top of the class file. This convention is used because
- The data are at the core of the class. By putting them at the headers' top they are highly visible, and conceptually form a block of data. This helps the class constructor to memorize what the internals of the class look like whenever any form of maintenance is performed.
- Support (private) functions are only infrequently used by the class developer and they are of course not directly called by the class's users. So, they can be `tucked away' at the bottom of the class.
- By separating the data members from the private member functions the header immediately indicates what is what. As data members can sometimes look like functions and as member functions can sometimes be used as though they are data members separating their locations in the header helps to solve any potential reader confusion.
- Once again, this is a design convention, but it turns out to be a very useful one: adopt it!
Don't over-elaborate. When designing your class do so like you do with functions: split up once it becomes too large. As a rule of thumb: if the (public) interface isn't completely visible on your editor's screen it's too big, and you should split it up into separate, more dedicated classes. Your functions' bodies should at most have some 20 lines from the opening curly to the closing curly.
Splitting is also indicated when you realize that some of your member functions do things that aren't really the `core business' of your class. Follow the one-class-one-responsibility rule. If members do things not fitting the class's responsibility encapsulate these tasks in a separate class and use local objects or composition to make their functionality available.
Avoid inline functions while constructing a class. While constructing a class you often encounter situations where such inline members need to be modified and then it's a pain to have to recompile all sources because the inline members' code will be `inlined' all over the place....
Member functions can be defined in-line if their code is smaller than their call (as a rule of thumb: this may hold true for functions consisting of at most one normal-sized statement) and if it can be assumed beyond reasonable doubt that their code remains unaltered.
When defining inline members, always make sure the class interface itself remains implementation-free. The class interface should contain only member function declarations.
Inline member functions, if used at all, should be defined in special files, e.g., having extensions .f for `function', which are included below the interface, as shown in the next example:
```
    class MyClass
    {
        size_t d_size;

        public:
            size_t size() const;
    };

    #include "size.f"
        
```
While size.f merely contains:
```
    inline size_t MyClass::size()
    {
        return d_size;
    }
        
```
This approach has multiple advantages:
- It keeps the file showing the class-interface absolutely clean, not confusing declarations with implementations;
- If at some point you'd like to change the status of a member from inline to normal, you merely have to remove the include (from the header), to replace the keyword inline by a line like #include "myclass.ih", and to rename the .f file to a .cc file.
- Conversions from normal to inline are realized likewise.
- Especially during later parts of this course: implementations of templates must be available in header files. By using the .f convention we retain the advantages of implementation-free headers we also enjoy with standard, statically compiled functions (i.e., functions implemented in .cc files)
Note that private inline members (or their .f files) should not be included in the class's header file as they are never used outside of the class. Instead, define (or include the .f files of) private inline members in the internal header file.
An exception to this rule is occasionally encountered with inline public members calling inline private members. In this situation the inline private member must also be defined in the class's header file.
A side note: when creating a library the class's header files are made available for inclusion by other programs. In those cases create those header files from the project's header file + .f files by including the .f files into the `exported' header file. Using the .f files convention is primarily for the benefit of the developer. Users of a class shouldn't have to inspect the header files anyway; they should be given a decent man-page.
Use member initializers whenever possible (but prefer initialization of data members in class headers if at all possible).
When using :, starting member initializer specification(s), use the preferred layout of opening curly ({) characters:
- they should be written on a line of their own, lined-up with the 1st character of the constructor's header;
- write every initializer specification on a line by itself, indented wrt to the : position;
- the curlies surrounding the constructor's body use the same indentation as the member initializer's initial : character.
Example:
```
    Demo::Demo(int value, string text)
    :
        d_value(value),
        d_text(text)
    {
        ... body statements
    }
        
```
Never abandon data hiding. Accessors defined inline allow clients to access the data at no additional cost of a function call and ensure that your clients don't have to rely on your implementation details. CAVEAT: once you use inline accessors the locations of the data members are fixed in the inlined code. Consequently, you can not reorder your class's data members anymore; if that's ever necessary you'll have to recompile all source files using the inlined accessors.
When defining accessors, make an educated guess how often they will be called in programs. If they're probably called multiple times (> 1) then define a data member holding the value returned by the accessor. Usually the returned value can be computed at construction time (this is the preferred approach). It's also possible to do 'lazy computation': don't actually compute the returned value until requested for the first time. The next time the accessor is called it should be able to detect that the value has already been computed so it can return the available value. This involves evaluating a condition, which can easily be avoided. The latter approach is defensible if it is unclear if the accessor is ever called and when determining the value to return is a very expensive operation.
Seriously consider using precompiled headers for your classes' internal header files. If you're using icmake and follow the design principles we advocate. Using precompiled headers in that case is as simple as changing the line
```
//#define SPCH ""
        
```
to
```
#define SPCH ""
        
```
in the file icmconf.

When defining static data resist the temptation to initialize them in the header. Although that is sometimes possible, it's unclear where those static data are actually defined, and so if you ever have to change their initializations you frequently end up having to recompile all your files. Instead, use a file data.cc in which you define and initialize the static data. That way the header remains as it should: it declares instead of defines the class's elements.

The above reasoning does not hold true when initializing data members in class header files, because those initializations are used by default in constructors that do not explicitly initialize those members. In constructors it's always possible to overrule the default by explicitly initializing those header-initialized data members.

Pointers

Especially when pointers are new to you, make a drawing to visualize what your pointers are pointing at and showing what happens when using/modifying pointers. Draw pointer variables as a little variable rectangle from which an arrow emerges. Unless clearly pointing at a specific location let the arrow end in a question mark. E.g.
```
    +-------+
    |    ---|---> ?
    +-------+
        
```
Likewise, let a 0-pointer point at 0:
```
    +-------+
    |    ---|---> 0
    +-------+
        
```
With fixed-size arrays the range-based for loop can often be used. See the Annotations for details.
Using NULL is old-school C programming. Use 0 (a plain zero) or nullptr (nullptr is only necessary to distinguish between overloaded functions when one function uses, e.g., an int parameter and another uses, e.g., a char * parameter).
Always match new with delete, match new[] with delete[] and operator new with operator delete
A dereferenced pointer to a multidimensional array is itself a pointer. Consider:
```
        int array[3][5]     
        int (*ptr)[5] = array   // note the parentheses!
            
```
Now, *ptr points to array's 1st row, and thus has type int *.
Don't use C's allocation functions like malloc(), free(), calloc(), realloc(). Instead use the C++ operators new, new[], operator new, delete, delete[] and operator delete. They're type-safe and prevent your program from continuing when the allocation fails.

Prefer for-loops accessing array elements using pointer variables over for-loops using size_t loop control variables and index expressions. This avoids the repeated evaluations of index expressions. E.g.,


        // rather than, assuming 'Type array[size]'
    for (int idx = 0; idx != size; ++idx)
        array[idx] = whatever();

        // use:
    for (Type *begin = array, *end = array + size; begin != end; ++begin)
        *begin = whatever();

If the `world of pointers' is new to you, you might want to try the variable declarator (VD) program: vd-1.03.tar.gz. Unpack and read the README file for further instructions.
Do not define zero-length arrays (e.g., string *sp = new string[0]). They are pointless and useless. To initialize a pointer to an array for which no elements are as yet available simply initialize it to 0 (string *sp = 0), allowing you to check for this value to infer that it doesn't point to elements yet.
When passing arrays to functions you usually also have to provide the number of elements in that array to the function. This can be done for real arrays in a non-magical way:
```
    Type array[] = { ,-separated list of Type values };
    size_t const sizeOfArray = sizeof(array) / sizeof(Type);
    // or, sometimes shorter:
    size_t const sizeOfArray = sizeof(array) / sizeof(array[0]);
        
```
This is always correct. You don't have to count, and later on array can be modified resulting in a new, again correct, value of sizeOfArray.

pointers2:

By convention: declare destructors immediately below the constructor(s). If no constructors are declared then declare the destructor as the first item in your class interface.
Do not use [] when defining array parameters of functions. Since the parameter is always a pointer define it as a pointer. Note that the pointer must be protected by parentheses when defining a parameter pointing to a multi-dimensional array.
The placement new operator operates on bytes of `raw memory'. Therefore, operator new allocating a block of raw memory returns a void *. However, if the type of information stored in the raw memory is Type then the bytes are to represent Type objects, of which there may be d_size out of a potential d_capacity number of objects. Thus, when the raw memory becomes available indicate that the raw bytes are to represent Type objects, by encapsulating the raw memory allocation in the following function:
```
    Type *newRaw(size_t requestedNoOfObjects)
    {
        return  static_cast<Type *>(
                        operator new(requestedNoOfObjects * sizeof(Type))
                );
    }
        
```
and let the remaining software simply refer to Type elements accessed using a Type * pointer.
Once d_size objects are stored at the location returned by newRaw, with Type *d_ptr having received newRaw's return value, then another support function comes in handy to properly delete the objects and the allocated raw memory. Here is a function deleteRaw complementary to newRaw, performing the object destruction and the deletion of the raw memory:
```
    void YourClassName::deleteRaw()
    {
        for (Type *ptr = d_ptr + d_size; ptr-- != d_ptr; )
            ptr->~Type();                     // directly call the 
                                              // object's destructor

        operator delete(d_ptr);               // release the raw memory
    }
        
```
Note that newRaw is defined as a free function: it has no class name scope. It doesn't need one, since no data members are used. You could consider storing newraw.o in a library (e.g., libtools.a) which can be used by any of your programs. In that case also define, e.g., a tools.h header file declaring newRaw. To use newRaw in your code your programs now merely heave to include tools.h, and you should link those programs (also) against libtools.a.
Alternatively, newRaw could be defined as a class member. If so, either define it as a const member function, or define it as a static member.
Never define a destructor using inline, but always define it in a source file of its own, even if it looks like this:
```
    Class::~Class()
    {}
        
```
At some point the compiler must define a table with pointers to member functions. If it finds the class's destructor's source file then it stores that table in the desstructor's object file. If there isn't a destructor, it's undefined where the compiler will store that table, highly complicating program maintenance.

General Hints, Tips and Tricks for C++

Frank B. Brokken / Jurjen Bokma