[Ffmpeg-devel] [PATCH] video4linux2 input

[Diego Biurrun]

On Wed, Feb 01, 2006 at 03:15:02PM +0100, Michael Niedermayer wrote:
> 
> On Wed, Feb 01, 2006 at 12:35:38PM +0100, Diego Biurrun wrote:
> > 
> > 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:

Yes, I agree, good variable names are a very important part of making
code readable.

> 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;

Benjamin, listening? ;)

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

Reimar, listening? ;)

> 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

Agreed.

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

Benjamin, listening? ;)

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

Michael, listening?  Oh, you wrote this yourself..  What you haven't
fixed it yet? ;-p

> 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;

The last comment is redundant but I would disagree about the other two,
not everybody remembers CIF/QCIF resolutions offhand...  IMO this is a
good example of how two small comments make the code more readable.  If
you care about vertical space you can put them at the end of the line...

> 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 ;)

Of course.

> 5. writing comments in a language other then english

Of course.

Diego