begin quoting Andrew Lentvorski as of Sun, Mar 16, 2008 at 05:21:11PM -0700: > SJS wrote: > >begin quoting David Brown as of Sun, Mar 16, 2008 at 04:38:35PM -0700: [snip] > >> It's this kind of thing I'm > >>referring to: > >> > >> /* FUNCTION blort > >> * > >> * arg1 - An integer argument. > >> * arg2 - A string argument. > >> * returns an integer > >> */ > >> int blort (int arg1, char *arg2); > >> > >>The best indicator of what the argument is for would be it's name. A > >>comment should not explain that it is an integer, but what is its meaning. > >>Is it a count of something, or an index, or something else. > > > > /* blort > > * > > * This function blortifies the specified string (in-place) and > > * answers the number of changes made, or answers a negative value > > * if the string is malformed (or some other error occurs). > > * > > * arg1 - A non-negative integer value indicating the degree of > > * desired transformation. Note that prime values are > > * isomorphic transformations. > > * arg2 - A non-null modifiable blortifiable string. > > * returns negative values on error, otherwise the number of changes > > * made. > > */ > > int blort( int arg1, char *arg2 ); > > And I would hurt you both right off the bat for arg1, arg2.
Heh. I wouldn't blame you. I'd probably hand you the stick. :) In my defense, I was not looking at the interface so much as fleshing out the comment. > Those better be something like: > > (int transformLevel, char* blortString) Doesn't C allow for "int blort( int, char * );" anyway? > Unfortunately, this is a *classic* C failure mode. Since nobody has an > editor that does autocomplete in C, everybody writes cryptic variable > names. Autocomplete messes me up more than it helps. -- Autocomplete has gotten better now that it waits for me to stab tab. Stewart Stremler -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
