Re: [Openocd-development] [PATCH] arm7_9_common: Documentation and typos
On Thu, 2009-05-21 at 19:49 -0500, Dean Glazeski wrote: Dean Glazeski dngl...@gmail.com Applied r1880. --Z ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] [PATCH] arm7_9_common: Documentation and Typos
On May 19, 2009, at 10:42 PM, Zach Welch wrote:
On Tue, 2009-05-19 at 22:14 -0700, David Brownell wrote:
On Tuesday 19 May 2009, Dean Glazeski wrote:
changed all 'struct target_s' to 'target_t' to keep things
consistent.
I'd rather do away with all typedefs myself, except maybe
for int variants. Ditto that *_t convention.
Anyone feel strongly pro-typedef?
I think typedefs have their place, but I agree they are BAD when
used in
header file declarations.
It all depends. I've seen really horrible uses of typedefs and I've
seen really good use of typedefs. For example, an opaque handle that
is provided to callers of an API to track a resource is really nice as
a typedef. Sure, you can use the socket approach and hand back an int
or you could hand back a pointer to a forward-declared struct, but
that makes the API unnecessarily ugly or confusing. Instead, a
typedef clarifies that the argument is a handle as opposed to an
arbitrary int and allows an easy change in the backing type assuming
everyone recompiles.
I'm not a fan of things like 'typedef uint32_t UInt32'. That is
redundant and only serves as a bad hack instead of a search and replace.
Why? Because 'struct foo' can be forward-declared safely if it will
be
used only for pointers.
If a header includes a 'typedef struct foo foo_t', you can safely
write foo_t * if you want to include the header or 'struct foo *' if
you don't. The typedef just gets rid of the C oddities of putting
structs and enums in their own namespaces.
In turn, this allows header files to be
decoupled from one another. Go back and look at the changes that I
started to decouple the headers and you will see me _removing_
typedefs
to accomplish that mission.
Technically, the typedefs didn't need to be removed to accomplish
that. In fact, the removal of the typedefs can easily cause more
confusion. For simple structs, this isn't necessarily a problem, but
more complex types easily show the benefits of typedefs. Consider the
following:
int list_item_next(struct item * head, struct item * cur, struct item
** next);
versus
typedef enum {
...
} list_error_t;
typedef struct item * list_item_t;
typedef struct item * list_t;
list_error_t list_item_next(list_t head, list_item_t cur, list_item_t
* next);
Technically both have the same behavior, but the second makes the
expected arguments clearer (don't pass an arbitrary element as the
head of the list, next is a value-return param, etc). It also allows
the API to change the underlying representations of the types without
the caller changing (but a recompile might be necessary).
As a result, the changes in this patch result in the system being more
tightly coupled than it really needs to be (and takes it in the
opposite
direction that it should be headed), so I am fairly strongly against
applying it without first seeing the typedef changes removed.
typedefs do not introduce strong coupling in any way. There is still
an option to use the forward declaration via the struct when
necessary. Of course, the use of the struct should only be reserved
for those cases where it needs to be a forward declaration to avoid
include loops.
Other than that, it looks great, and I am really appreciating the
work!
Cheers,
Zach
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
--
Rick Altherr
kc8...@kc8apf.net
He said he hadn't had a byte in three days. I had a short, so I split
it with him.
-- Unsigned
smime.p7s
Description: S/MIME cryptographic signature
___
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] [PATCH] arm7_9_common: Documentation and Typos
On Tue, 2009-05-19 at 23:17 -0700, Rick Altherr wrote: On May 19, 2009, at 10:42 PM, Zach Welch wrote: On Tue, 2009-05-19 at 22:14 -0700, David Brownell wrote: On Tuesday 19 May 2009, Dean Glazeski wrote: changed all 'struct target_s' to 'target_t' to keep things consistent. I'd rather do away with all typedefs myself, except maybe for int variants. Ditto that *_t convention. Anyone feel strongly pro-typedef? I think typedefs have their place, but I agree they are BAD when used in header file declarations. It all depends. [snip] Yes, thanks for providing a clearer explanation; however, I do not think that this thread fully resolves the topic. To do that, I think we need to expand the documentation to provide style rules for using typedefs in the OpenOCD code, as no rules cover this particular element at the moment (other than emulate). I cannot discern clear rules from the examples that I have read on this list or in the code, so I think there may need to be a brief discussion on the topic to resolve it fully. I will post a new thread shortly. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] [PATCH] arm7_9_common: Documentation and Typos
On Tuesday 19 May 2009, Øyvind Harboe wrote: I'd rather do away with all typedefs myself, except maybe for int variants. Ditto that *_t convention. Anyone feel strongly pro-typedef? I think that typedefs are useful when a level of indirection is needed, it is non-trivial to define the type(u32, u8, intptr_t, etc.) or the type itself is horrible to spell out(pointer to a function which takes a pointer to) That non-trivial encapsulates the portability issues; those all boil down to needed. Except, in some cases, the function typedef ... I'd rather see those spelled out in most signatures, but there are cases where that's just on the wrong side of too painful. When the type is striaghtforward(int or struct), then typedef can make things less readable. typedef struct x x_t is such an example. Right. ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] [PATCH] arm7_9_common: Documentation and Typos
On Wed, May 20, 2009 at 7:14 AM, David Brownell davi...@pacbell.net wrote: On Tuesday 19 May 2009, Dean Glazeski wrote: changed all 'struct target_s' to 'target_t' to keep things consistent. I'd rather do away with all typedefs myself, except maybe for int variants. Ditto that *_t convention. Anyone feel strongly pro-typedef? I think that typedefs are useful when a level of indirection is needed, it is non-trivial to define the type(u32, u8, intptr_t, etc.) or the type itself is horrible to spell out(pointer to a function which takes a pointer to) When the type is striaghtforward(int or struct), then typedef can make things less readable. typedef struct x x_t is such an example. -- Øyvind Harboe Embedded software and hardware consulting services http://consulting.zylin.com ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] [PATCH] arm7_9_common: Documentation and Typos
On Tue, 2009-05-19 at 22:14 -0700, David Brownell wrote: On Tuesday 19 May 2009, Dean Glazeski wrote: changed all 'struct target_s' to 'target_t' to keep things consistent. I'd rather do away with all typedefs myself, except maybe for int variants. Ditto that *_t convention. Anyone feel strongly pro-typedef? I think typedefs have their place, but I agree they are BAD when used in header file declarations. Why? Because 'struct foo' can be forward-declared safely if it will be used only for pointers. In turn, this allows header files to be decoupled from one another. Go back and look at the changes that I started to decouple the headers and you will see me _removing_ typedefs to accomplish that mission. As a result, the changes in this patch result in the system being more tightly coupled than it really needs to be (and takes it in the opposite direction that it should be headed), so I am fairly strongly against applying it without first seeing the typedef changes removed. Other than that, it looks great, and I am really appreciating the work! Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
