Re: zsh coding style (was about a limit patch review)

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Stephane Chazelas wrote on Sat, Nov 28, 2020 at 06:52:01 +0000:
> 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.

Every docstring should state the permitted values of each parameter and the
possible return values.  Yes, some existing functions fall short of this
standard, but there's no reason not to hold _new_ functions to it.  That
doesn't pay off existing technical debt, but it avoids accruing further debt.

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

No, I'm not.

> 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 hear it's more common in lisp circles.  It's a form of Hungarian notation.

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

I wasn't trying to enforce a new coding style.  I was simply reviewing the
docstring to the same standard I've reviewed every other docstring I've ever
reviewed, either on this list or elsewhere.

Cheers,

Daniel