Documenting code

Applications Programming
1

I am programming using C++ and am wondering how to comment my project.

For example, when I declare a class I created a header with some description, then have the declaration stage, which I don't comment. Then when I define the actual functions I will put details about it, what it does, description of arguments etc.

Would be good to have people's opinion on this.

//  class Matrix
//
//    The Matrix class defines and implements manipulation functions
//    for matrices.
//
//  History:
//    V01 - DEC 1999 - Luca D'Auria
//          Initial release.
//    V02 - SEP 2008 - Luca Elia
//          Version fixed for g++ 4.3.0.
//    V03 - NOV 2008 - Christopher Dimech
//          Code restructuring.

#ifndef MATRIX_H
#define MATRIX_H

#include <assert.h>
#include "vector.h"

template <class Type>
class Matrix {

public:

  Matrix();

  Matrix(
    const int  m,
    const int  n );

  Matrix(
    const Matrix&  A );

  ~Matrix();

  void
  resize(
    const int  m,
    const int  n );

  void
  fill(
    const Type  val );

...
2

You should put the description in the header because that's where everyone's going to look. It means they don't need to hunt through hundreds of lines of source to find the function implementation they're interested in.

Besides -- if you ever distribute this code in library form, your users won't even have the source files, just the header and some objects.

3

I can put documentation for the interface (parameters, return value, what the function does) in the interface file (.h), and the documentation for the implementation (how the function does) in the implementation file (.c, .cpp, .m).

I can also document the interface (return values, argument, state changes, etc) before the member function implementation, and high-level architectural overviews in separate documents (to give a broader view of how everything is put together; it's hard to place this together with the code, since it usually references several classes at once).

I write an overview of the class just before its declaration, so the reader has immediate basic information.