zsh coding style (was about a limit patch review)

[Stephane Chazelas <stephane@chazelas.org>]

2020-11-27 20:36:40 +0000, Daniel Shahaf:
[...]
> Of course, DRY; but still, notice how one of the ints is actually
> a boolean, so the formal type information doesn't convey everything.
[...]
> > + * Arguments:
> > + *   - s: string to parse
> > + *   - lim: resource being limited (from which will derive the type and unit)
> > + *   - ulimit: to specify whether we're being called by ulimit or not.
> > + *             For ulimit, suffix-less limits are multiplied by the limit's
> > + *             unit.
> 
> Suggest to add the word "boolean" to the description of this parameter.
> 
> Since you've already gone and described it in prose, I'd consider to
> also rename it to something like
> «multiply_suffixless_limits_by_implied_unit_p» (trailing _p for
> "predicate", i.e., signifies the variable is a boolean), to avoid caller–callee coupling.
> 
> > + *   - err: (return value) error to be returned if any. If a non-NULL value is
> > + *           stored there, zstrtorlimt failed and the return value is
> > + *           irrelevant (though will be 0).
> 
> You don't actually say anywhere what the return value will be when there
> _isn't_ an error.
[...]

Believe it or not, I had "(boolean)" and a "Returns:..."
initially, and took them out before submitting as they would
have been out of character among the other functions in that
file (and the rest of the code from a cursory look) which are
rather minimalist and avoid stating the obvious.

This function description is already by far the least dry and
probably the most RY in that file. To the point that I'm
wondering if you're pulling my leg for being overly wordy here.

About the _p suffix, the only usage of it in the code (beside
has_p) I could find for it was 
save_params(Estate state, Wordcode pc, LinkList *restore_p, LinkList *remove_p)
in exec.c, but that "p" looks like it's for "pointer" (as in
return value, though could also be "param"), not "predicate".
I've never heard of _p for predicate before, but then again I've
not done much C development lately.

I'm all for having a coding style. Even a template for function
header could be useful. That would probably help make the
code more legible (though in general, I do find zsh's code
pretty legible, orders of magnitude more so than ksh93's for
instance)

I did read Etc/zsh-development-guide before submitting my first
patch. The relevant bit there is:

} * Function declarations must look like this:
} 
}   /**/
}   int
}   foo(char *s, char **p)
}   {
}       function body
}   }
} 
}   There must be an empty line, a line with "/**/", a line with the
}   type of the function, and finally the name of the function with typed
}   arguments.  These lines must not be indented.  The script generating
}   function prototypes and the ansi2knr program depend on this format.

Maybe that document could be updated to say more precisely how
new code should look like if we're to enforce a new coding
style.

-- 
Stephane