Rockbox.org home
release
dev builds
extras
themes manual
wiki
device status forums
mailing lists
IRC bugs
patches
dev guide



Rockbox mail archive

Subject: Re: Typedef rule

Re: Typedef rule

From: Amaury Pouly <amaury.pouly_at_gmail.com>
Date: Fri, 29 Nov 2013 14:14:47 +0000

2013/11/29 Thomas Martitz <kugel_at_rockbox.org>

> Am 29.11.2013 09:27, schrieb Thomas Martitz:
>
> Hello,
>>
>> as you know we have a "no typedef rule" in our guidelines. However there
>> are a few problems with it when applied to integral types:
>>
>> * Portability is reduced, for example we use unsigned for thread ids but
>> pthread uses unsigned long (I have some work where we can use pthreads, at
>> least in parts). This could be handled better with a typedef.
>> * Readability is reduced, for example we use long for our tick. IMO
>> readability/expressiveness would be improved by refering to a "tick_t"
>> instead of ordinary long.
>> * Type checking is prevented, for example gcc could do better type
>> checking with proper typedefs. It's easy to think "I can use int instead of
>> long" when the global tick really needs to be a long.
>>
>> The Linux kernel coding guidelines have summarized the issues even
>> better: https://www.kernel.org/doc/Documentation/CodingStyle (chapter 5).
>>
>> Therefore I propose that we relax the typedef rule and allow typedefs for
>> integral types (only) when reasonable. This would basically be adopting the
>> Linux kernel guideline w.r.t. to typedefs, except they allow typedefs for
>> "totally opaque objects (where the typedef is actively used to _hide_ what
>> the object is)."
>>
>>
>> In essence:
>> - No typedef for structs and unions. These types help with the
>> aforementioned problems by themselves.
>> - No typedef for pointers. Hiding a pointer between some type remains
>> silly.
>> - No typedef for trivial ints, like normal counters (except tick) or
>> something like that.
>> - Allow typedefs where reasonable, i.e. where it helps enforcing a
>> specific type, improves readability and portability.
>> - Allow typedefs for void, as to give "void *" a more telling type.
>>
>> I'd like to trust our developers to weigh up what's reasonable.
>>
>
>
> I was made aware that we should probably also adopt the above exception
> about totally opaque types, for cases where a type is a an integral type on
> platform a and some pointer on platform b (as is the case with pthread_t,
> apparently).
>
> Therefore I'd like to modify my proposal:
>
> (1) No typedef for structs and unions. These types help with the
> aforementioned problems by themselves. Don't typedef just to avoid writing
> out "struct" and "union".
> (2) No typedef for trivial ints, like normal counters (except tick) or
> something like that.
> (3) Allow typedefs where reasonable for integral types, i.e. where it
> helps enforcing a specific type, improves readability and portability.
> (4) Allow typedefs for void, as to give "void *" a more telling type.
> (5) Generally no typedef for pointers. Hiding a pointer between some type
> remains discouraged except in one case: Hiding that the type is a pointer
> at all, when the type is strictly used to identify an object (compatible to
> long/intptr_t). Typedefing a pointer might be okay if it points to an
> incomplete struct/union. This case is actually similar to (3) where you
> typedef intptr_t to something better named.
>
> Best regards.
>
Actually I was not aware that we had a typedef rule and I absolutely think
your proposal is reasonable. I think proper typing when properly used can
greatly enhance the code quality. So go for it !
Received on 2013-11-29


Page was last modified "Jan 10 2012" The Rockbox Crew
aaa