darkknight said:
Is there any commonest practice or "industry standard" regarding comments
that appear at the head of a function definition or function prototype?
Do they go in the .c file only, the .h file only or both?
What do the comments consist of?
Pre-conditions, post-conditions, inputs, outputs, behaviour?
/* Find a few eigenvalues in a complex hermitian matrix
using Lanczos' algorithm. */
nml_extent eigenvaluesLanczos(/* number of eigenvalues actually found */
nml_dvector *value, /* out real eigenvalue vector */
nml_d3bands *T, /* out symmetric tridiagonal matrix */
nml_extent *pIterations, /* out actual number of iterations */
nml_dcvector *r_n, /* inout r_{n} = q_{n+1}*beta_{n} */
nml_dcvector *q_n, /* inout current complex Lanczos vector*/
nml_dcvector *q_n1, /* inout previous complex Lanczos vector*/
nml_extent length, /* in extent of vectors r_n, q_n & q_n1 */
nml_extent requested, /* in requested number of eigenvalues */
int ConvCheckStartIter, /* in convergence check start iteration */
int ConvCheckSkipRate, /* in convergence check skip rate */
nml_extent imax, /* in maximum number of iterations + 1 */
nml_dscalar emin, /* in eigenvalue search lower bound */
nml_dscalar emax, /* in eigenvalue search upper bound */
nml_dscalar tolerance, /* in eigenvalue convergence tolerance */
nml_dscalar resolution, /* in eigenvalue separation minimum */
void (*matmul)(const int**, nml_dcscalar*, const nml_dcscalar*),
const int* argument[], /* matrix-vector multiply argument list */
FILE *fp_trace, /* inout trace log text file pointer */
FILE *fp_instant, /* inout instant log text file pointer */
FILE *fp_log, /* inout message log text file pointer */
int verbose /* in verbose diagnostic messages */
);
This is typical.
Yes, it should appear in *both* the interface (header) file
and in the implementation (source) file.
Try to identify the algorithm
that you are using.
Reference a textbook or paper if necessary.
That will save you a lot of unecessary comments.
Pass inputs by value or const reference [pointer].
I try to return by value but,
when outputs must appear in the argument list,
I like to put them first before any inputs.
Argument names appear in the function declaration
as well as the function definition and
are chosen carefully to help document the argument list.
