Re: [MERGE] Initial netfilter mark patch for comment

On 08/21/2010 05:45 PM, Henrik Nordström wrote:
> lör 2010-08-21 klockan 23:41 +0100 skrev Andrew Beverley:
>
>> I have documented all the functions and class data members. Could you
>> clarify whether *every* variable should be documented with doxygen
>> comments (including short-lived temporary ones within functions), or
>> just those that are part of classes/structs?
>
> classes/structs.
>
> temporary variables if their use may not be obvious to someone else
> reading your code, but preferably code in such shape that variable use
> is obvious.
>
>> For example, should 'tos' in the function below have doxygen comments?
>
> No need for that imho.

Agreed. Especially true if you select meaningful names for local
variables (e.g., "headerBuf" instead of "b" or "ipCount" instead of "c").

BTW, if the documentation comment simply spells out the variable name,
it is worse than no comment. For example,

private:
     int isFoo; ///< whether we are Foo

is useless but something like

     int isFoo; ///< caller expects Bar in the result

may shed more light than the variable name itself. Perhaps my
foo/bar-based example is too abstract to make sense, but try to explain
what the variable/function does to a person who could not guess it
correctly from the name alone or, if the name is really obvious/clear,
supply additional information instead of repeating (spelling out) the name.

Also, there is no requirement to document API implementation methods in
kids unless you want to:

/// such and such API
class Parent {
     /// checks computations results for exceeding INT_MAX
     virtual bool willFit() const = 0;
     virtual int calc() = 0; /// ...
     ...
};

/// Foo and bar, using such and such API
class Child: pubic Parent {
     ...

     /* Parent API */
     virtual bool willFit() const;
     virtual int calc();
     ...
};

HTH,

Alex.
Received on Sun Aug 22 2010 - 13:26:02 MDT