svn commit: r368714 - head/lib/libc/string

[Kevin Bowling]

On Thu, Dec 17, 2020 at 9:33 AM Ian Lepore <ian at freebsd.org> wrote:

> On Thu, 2020-12-17 at 18:22 +0200, Konstantin Belousov wrote:
> > On Thu, Dec 17, 2020 at 01:01:01PM +0000, Jessica Clarke wrote:
> > > On 17 Dec 2020, at 12:53, Konstantin Belousov <kostikbel at gmail.com>
> > > wrote:
> > > >
> > > > On Thu, Dec 17, 2020 at 12:41:47PM +0000, Mateusz Piotrowski
> > > > wrote:
> > > > > Author: 0mp (doc,ports committer)
> > > > > Date: Thu Dec 17 12:41:47 2020
> > > > > New Revision: 368714
> > > > > URL: https://svnweb.freebsd.org/changeset/base/368714
> > > > >
> > > > > Log:
> > > > >  strerror.3: Add an example for perror()
> > > > >
> > > > >  This is a nice and quick reference.
> > > > >
> > > > >  Reviewed by:   jilles, yuripv
> > > > >  MFC after:     2 weeks
> > > > >  Differential Revision: https://reviews.freebsd.org/D27623
> > > > >
> > > > > Modified:
> > > > >  head/lib/libc/string/strerror.3
> > > > >
> > > > > Modified: head/lib/libc/string/strerror.3
> > > > > ===============================================================
> > > > > ===============
> > > > > --- head/lib/libc/string/strerror.3     Thu Dec 17 03:42:54
> > > > > 2020    (r368713)
> > > > > +++ head/lib/libc/string/strerror.3     Thu Dec 17 12:41:47
> > > > > 2020    (r368714)
> > > > > @@ -32,7 +32,7 @@
> > > > > .\"     @(#)strerror.3  8.1 (Berkeley) 6/9/93
> > > > > .\" $FreeBSD$
> > > > > .\"
> > > > > -.Dd December 7, 2020
> > > > > +.Dd December 17, 2020
> > > > > .Dt STRERROR 3
> > > > > .Os
> > > > > .Sh NAME
> > > > > @@ -170,6 +170,31 @@ The use of these variables is deprecated;
> > > > > or
> > > > > .Fn strerror_r
> > > > > should be used instead.
> > > > > +.Sh EXAMPLES
> > > > > +The following example shows how to use
> > > > > +.Fn perror
> > > > > +to report an error.
> > > > > +.Bd -literal -offset 2n
> > > > > +#include <fcntl.h>
> > > > > +#include <stdio.h>
> > > > > +#include <stdlib.h>
> > > > > +
> > > > > +int
> > > > > +main(void)
> > > > > +{
> > > > > +       int fd;
> > > > > +
> > > > > +       if ((fd = open("/nonexistent", O_RDONLY)) == -1) {
> > > > > +               perror("open()");
> > > > > +               exit(1);
> > > > > +       }
> > > > > +        printf("File descriptor: %d\en", fd);
> > > >
> > > > This lines is indented with spaces, while other lines have tabs.
> > > >
> > > > > +       return (0);
> > > >
> > > > return (0) is redundand.
> > >
> > > It's not required as per the standard, but omitting it is needlessly
> > > obfuscating it and bad practice. C lets you do a whole load of things
> > > that are a bad idea, and whilst this one is harmless, it is nonetheless
> > > confusing to anyone who is not intimately acquainted quirks like this
> > > special case in the standard.
> >
> > Why it is bad practice ?
> >
> > C is a small language, and while knowing some quirks (like this one)
> > seems to be optional, others are not. And worse, that other quirks are
> > essential for writing correct code at all. Consequence is that ignoring
> > details indicates insufficient knowledge of the fundamentals and lowers
> > the trust in the provided suggestion.
>
> I completely disagree.  Writing example code where you fail to return a
> value and just fall out the bottom of some function that declares it
> returns an int is just Bad Code.  Using some obscure quirk of the
> language as justification for that bad code doesn't help the situation
> at all.
>
> How obscure is this quirk?  I've been writing C code since 1983,
> including having released a freeware compiler (pre-gcc days) and
> working on a commercial C compiler.  I used to moderate the c_language
> conference on BIX (back when that was a thing).  I make my living
> writing C and C++ code every day.  And yet, I had completely forgotten
> about this quirk.
>
> Example code shouldn't be used to establish how much more clever you
> are than the reader, it should be as easy to understand as possible.
>
> -- Ian


In Kib’s defense I think this is commonly mentioned in C99 books (at least
that’s where I learned of it) so it depends on when and where someone
learned.  There are merits approaches of being explicit or brief.  I have
no preference directly but we should probably try to be uniform in our
examples with whatever is most common in the docs already.

>