[Ffmpeg-devel] [PATCH] video4linux2 input (original) (raw)

Michael Niedermayer michaelni
Wed Feb 1 15:15:02 CET 2006

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

  1. 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++; // "("

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

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

  2. writing comments in a language other then english

[...]

-- Michael

More information about the ffmpeg-devel mailing list