On Tue, Jun 09, 2020 at 08:19:53PM -0700, jo...@armadilloaerospace.com wrote:
> Also, style(9) says that prototypes should not have variable names
> associated with the types. I try to use good names in the headers
> for documentation purposes; what is the thinking behind the rule?
function names are part of the API, variable names are not. Indeed they
are like comment, but deadly comments, because they are still part of
the namespace, hence susceptible to yield issues with macros.
In your example,
> int pcdisplay_copycols(void *id, int row, int srccol, int dstcol, int
> ncols);
> vs:
> int pcdisplay_copycols(void *, int, int, int,int);
>
first one won't compile if there is a
#define row (getenv("ROW"))
in effect.
Also, even with variable names, it's possible to mix-up parameters with
similar types.
That rule is somewhat controversial though.
I personally tend to prefer actually documenting what the function does in
a comment in the header, and comment how it does it in the source file.
