C++ Tutorial: Commenting and Neatness

[GFreak45]

Neatness:

Neatness is huge to every programmer, proper indentation and spacing is important for read-ability, and properly named variables is also important to help the reader understand and recognize what exactly is what.

Indentation:

Every scope ({} symbols), or list of multiple variables on 1 type (int x, y), should be indented 1 tab or 4 spaces, depending on the compiler that you use. Microsoft Visual Studio C++ automatically uses tabs, Dev C++ automatically uses spaces, etc. Your end result should be easily legible if you follow the indentation. ie:

void thisIsAFunction ()
{
    cout << "And it does stuff.\n";
    if (rand() % 2)
    {
        cout << "Lots of stuff.\n";
    }
    else
    {
        cout << "Really cool stuff.\n";
    }
}

Naming Conventions:

Wording:

Variable names (in most cases) should be slightly descriptive, to give the user an idea of exactly what the programmer is doing, the exception to this case, is a loop's variable, which is commonly named a letter, most commonly x, y, z, i, or j.

Cases:

• Non-constant Variables - camelCase (first letter of first word lower case, first letter of additional words are upper case, cant start with numbers)
• Constant Variables - UPPER_CASE (all letters upper case, words seperated by underscores)
• Function and class names - User preference, common conventions are camelCase or NormalCase (first letter of all words upper case)

Commenting:(yes a tutorial on commenting)

This section will have multiple sub-sections, and based on how advanced you may be, some sections may not pertain to you at the moment.

Functions:

Function commenting is usually done near or around the function prototypes. A basic function comment has a few lines: 1 for name and simple description, 1 for each argument, and 1 for return (if not void), ie:

int add (int, int);
//add - adds 2 numbers together
//@param int - the first number
//@param int - the second number
//@return int - the first and second numbers added together
 
int main ()
{
    return 0;
}
 
int add (int a, int b)
{
    return a + b;
}

Notes:

• Overloaded Functions should say so in the first line ie: //add - (overloaded) does...
• Optional Parameters should say so in the argument line, ie: int - (optional) some number

Classes:

Classes have multiple types of methods, and those include the following:

• Constructors - ways of constructing each object
• Destructors - ways of destroying each object
• Accessors - methods that do not modify any of the calling object's values (const modifier)
• Mutators - methods that do modify the calling object's values (not const)
• Overloaded Operators - exactly what it sounds like
• Properties - psuedo-members that allow a variable-like syntax when actually using methods
• Nested Classes - should only be included if there are any nested classes

For Example:

class Example
{
public:
 
        /* Constructors */
 
    Example ();
    //Default Constructor
 
    Example (int);
    //Overloaded Constructor
    //@param int - the initial value of the x member
 
        /* Destructors */
 
    ~Example ();
    //Default Destructor
 
        /* Accessors */
 
    int getX () const;
    //getX - gets the value  of the x member
    //@return int - the value of the x member
 
        /* Mutators */
 
    void setX (int);
    //setX - sets the value of the x member
    //@param int - the new value of the x member
 
        /* Overloaded Operators */
 
    int& operator++ ();
    //operator++ - increments the x member by 1
    //@return int& - a reference to the x member
 
        /* Properties */
 
    __declspec(property(put = setX, get = getX)) int X;
    //int X - the only member recording any value in the class
 
private:
    int x; //note the names of X and x are different, if they are the same it will create an error
}

Templates:

Templates are essentially the same as functions in their commenting, but slightly different, ie:

Functions:

template<class T>
T someFunction ();
//someFunction - does something
//@template class T - the return type of the function
//@return T - some value of type T

Classes:

template<class T>
//@template class T - the type the class holds
class someClass
{
public:
    T value;
}

If there are any questions or instances to add simply post them here and I will attempt to update the commenting on it as soon as possible.