[Ffmpeg-devel] [PATCH] video4linux2 input

[Michael Niedermayer]

Hi

On Wed, Feb 01, 2006 at 12:35:38PM +0100, Diego Biurrun wrote:
[...]
> > (doxygen) comments are always good if looking at the function/loop/... for
> > a minute isnt enough to understand it, and they are often bad if the code 
> > is trivial anyway (its like adding whitespace or random junk which makes
> > reading harder, allthough it gives the impression to some people the code
> > becomes more understandable, its like 5min to understand 1 line vs. 5min
> > to understand 1 page of code but both do the same thing, later gives the
> > impression of being easier to understand ...)
> 
> Please don't forget that not everybody has your coding skills.  Lesser
> coders might profit more from a few explanatory comments.

yes, but comments should be writen carefully, there are a few stupid things
people frequently do

1. choose bad name and fix it by a comment: for example:
cook.c-    int                 numvector_bits;
cook.c:    int                 numvector_size;                //1 << numvector_bits;

could be:

cook.c-    int                 log2_numvector_size;
cook.c:    int                 numvector_size;

or:

cscd.c:        case 0: { // lzo compression
this should obviously be an enum or #define


2. use a comment for an assert() not only cant that be checked
automatically, its also often unclear if the comment is some optional
debuging code or some always true statement

cook.c-            if (q->samples_per_channel > 256) {
cook.c:                q->numvector_bits++;   // q->numvector_bits  = 6
cook.c-            }

or

eval.c:    p->s++; // "("


3. simply unneeded comments which make reading more difficult:

h261.c:    // QCIF
h261.c-    if (width == 176 && height == 144)
h261.c-        return 0;
h261.c:    // CIF
h261.c-    else if (width == 352 && height == 288)
h261.c-        return 1;
h261.c:    // ERROR
h261.c-    else
h261.c-        return -1;

4. using comments to document logical subparts of a function instead of
spliting the function into several, look at any file i wrote for examples ;)

5. writing comments in a language other then english


[...]

-- 
Michael