On Fri, Jan 22, 2016 at 09:34:28PM +0000, Rainer Weikusat wrote:
> Can the effect of the following C function
>

> static void print_start(char const *name, char const *what)
> {
>     char *buf, *p;
>     unsigned name_len, what_len, total;

>

>     name_len = strlen(name);
>     what_len = strlen(what);
>     total = name_len + what_len + 3;

>

>     p = buf = alloca(total);
>     memcpy(p, name, name_len);
>     p += name_len;
>     *p++ = ' ';
>     memcpy(p, what, what_len);
>     p += what_len;
>     *p++ = ':';
>     *p = ' ';

>

>     *buf &= ~0x20;

>

>     Write(2, buf, total);
> }

>
> be considered obvious or should it rather get an explanation?
> ?
> An ASCII lowercase letter can be turned into the corresponding uppercase
> letter by clearing the sixth bit.
> _______________________________________________

My answer is that you shouldn't assume someone will understand what
your function does, even if you think a five-year-old should get
it. It's always a good idea to include a comment block at the top of
your function describing what it does, what variables it expects, and
what it does (or in this case) doesn't return. Yes, that means
explicitly state a void function returns no value. If nothing else,
you do someone else the courtesy of saving them time by explaining
what your function does so they don't need to read through it to
figure that out. If they want to read through it anyway, they still
have that option of course. Just my $0.01 worth.

Greg


--
web site: http://www.gregn.net
gpg public key: http://www.gregn.net/pubkey.asc
skype: gregn1
(authorization required, add me to your contacts list first)
If we haven't been in touch before, e-mail me before adding me to your contacts.

--
Free domains: http://www.eu.org/ or mail dns-manager@???