On Fri, Mar 22, 2024 at 4:58 PM Tristan Partin <tristan@neon.tech> wrote:
> I had a question about parameter naming. Right now I have a mix of
> camel-case and snake-case in the function signature since that is what
> I inherited. Should I change that to be consistent? If so, which case
> would you like?
Uh... PostgreSQL is kind of the wild west in that regard. The thing to
do is look for nearby precedents, but that doesn't help much here
because in the very same file, libpq-fe.h, we have:
extern int PQsetResultAttrs(PGresult *res, int numAttributes,
PGresAttDesc *attDescs);
extern int PQsetvalue(PGresult *res, int tup_num, int field_num,
char *value, int len);
Since the existing naming is consistent with one of those two styles,
I'd probably just leave it be.
+ The function returns a value greater than <literal>0</literal>
if the specified condition
+ is met, <literal>0</literal> if a timeout occurred, or
<literal>-1</literal> if an error
+ or interrupt occurred. In the event <literal>forRead</literal> and
We either need to tell people how to find out which error it was, or
if that's not possible and we can't reasonably make it possible, we
need to tell them why they shouldn't care. Because there's nothing
more delightful than someone who shows up and says "hey, I tried to do
XYZ, and I got an error," as if that were sufficient information for
me to do something useful.
+ <literal>end_time</literal> is the time in the future in
seconds starting from the UNIX
+ epoch in which you would like the function to return if the
condition is not met.
This sentence seems a bit contorted to me, like maybe Yoda wrote it. I
was about to try to rephrase it and maybe split it in two when I
wondered why we need to document how time_t works at all. Can't we
just say something like "If end_time is not -1, it specifies the time
at which this function should stop waiting for the condition to be
met" -- and maybe move it to the end of the first paragraph, so it's
before where we list the meanings of the return values?
--
Robert Haas
EDB: http://www.enterprisedb.com
