Good Example in C++:

1. Comments are easy to change.
2. Comments are kept close to the code the described.
3. Each routine is described in one sentence.
4. Input and output variables are documented where they are declared.
5. Input and output data are differentiated.
6. Comments are in the intent level.

/*****************************************************************
	Triangle 	compute area of triangle
	Parameters
		width  --	width of the triangle
		height - height of the triangle
	Return	area of the triangle
	
******************************************************************/
# include <iostream.h>

// Function to compute the area of triangle
float triangleArea (float width, float height)
{  
    float area; // out: area of the triangle

    area = width * height / 2.0;
    return (area);
}

// Test routine for triangle function
int main ()
{
    float width;   //int: width of triangle
    float height;  //int: height of triangle

    //Function to compute area of triangle
    float triangleArea(float width, float height);

    // prompt use to enter input
    cout << "Enter the width of triangle: " ;
    cin   >> width;
    cout << "Enter the height of triangle: ";
    cin >> height;

    // Output the result
    cout << "The area of the triangle is " <<
                 triangleArea (width, heigh) << endl;

    return 0;
}

/*******************************************************************/

Output of execution:
Enter the width of triangle: 3.6
Enter the height of triangle: 4.0
The area of the triangle is 7.2