On May 25, 2009, at 12:28 PM, Zach Welch wrote:
1) It's shorter/faster to type. This argument has been hashed out extensively on the Linux mailing lists. Linus has it right in this debate to prefer s32/u32. POSIX is dumb; however, that doesn't mean we can't exploit their work for own purposes.Perhaps I'm jaded from writing code for OS X where function names areintended to be descriptive and thus end up long. Most editors includeautocompletion which makes the difference minimal in practice. Even when I'm writing code in vi, I prefer the longer type names since it make it clear that a) it's a type by having the _t suffix and b)that's an unsigned int. With u32, there are plenty of cases where odd naming collisions can occur. It's also not clear that its an integer,but just an unsigned 32-bit something. To be entirely honest, I prefer seeing long, descriptive function prototypes like: status_t TriggerSetThreadStateFilter(trigger_t trigger, const thread_state_t * stateMasks, uint32_t numberOfStateMasks, error_t * error); I pulled this particular example from another project I'm working on, but it should illustrate the point. You can understand what most of the parameters are and have a decent idea of what the function does. The compiler doesn't care about names, so we should optimize them for the people.Which people? People that need to have their hands held with longfluffy names? Or for advanced coders that they can handle (and prefer) the shorter conventions? We should not dumb-down the OpenOCD code, andthat is _exactly_ what you are describing.
New developers to the project. Not all advanced coders _prefer_ shorter names just to save on typing. I'm not suggesting we "dumb- down" anything. Using cryptic short names to save on typing is an elitist attitude that makes the barrier to entry for new developers higher and makes the time to come up to speed on a portion of the codebase longer. Code should be clear and concise. If a longer function name describes the effect of the function better, then it should be the longer name. That doesn't mean that every function should have a long name. Same for types. If a longer or additional type name would clarify the code, then it should be used. u32 doesn't clarify anything. It just replaces the familiar type defined by a well-known standard with something 5 characters shorter.
2) More importantly, this patch applies the principle of least change.These changes both unify the type system around the types that are defined in "types.h" (and with the Linux kernel). Thus, we achieveconformance to an internal (and external) standard that we can enforcefrom here on. With less typing (this goes both for the types themselves and for the changes necessary to convert the entire tree to use the types that are used in only a handful of files today).Given that the state of the code is a hodgepodge of various naming conventions, I don't see it being a good source for "it was mostlythat way already". I'd rather we chose a sensible convention based onmerits and apply it wholesale rather than just letting majority rule.Clearly you have not looked at the code with regard to this issue. The code is NOT a "hodgepodge" when it comes to these types.
I was referring to the grander concerns for following the "it was mostly that way already" philosophy. The use of types is probably the _only_ mostly consistent item in the whole source tree. I would hate to see the use of that philosophy here as justification for doing so in other cases.
Having the types align with the Linux kernel is of effectively no importance. I happen to do all my development on OS X which follows the C99 naming standards for anything in the BSD layer. Familiarity in this case doesn't hold across the gamut of our developer base.How about familiarity with the OpenOCD code, which uses these types? How about the fact that 99% of the OpenOCD code already uses them?
See above. It's more of a concern about the slippery slope on using that justification. Since you brought it up, however, there are ~10 people who are familiar with the OpenOCD code base. Any given new developer has a good chance of being unfamiliar with these types since they are far from a standard convention. Now, for u32 specifically, I don't think the jump is too hard, but if we go down this path of choosing type names that are optimized for typing, it can easily get out of hand and confusing. Just consider the short form of intmax_t following the convention proposed: smax. Tell me that that has a low chance of being confusing or hitting conflicts. Do we also shorten the type names for things like struct jtag_tap_s? Does it become 'j', 'jtag', 'tap', ...?
Sorry Rick, but I think that you and Duane have lost this argument. You have failed to defend your position with facts.
I could say the same of everyone else. Considering the entire issue is rooted in preference, there are no hard facts to be presented. Some prefer to have shorter names, some prefer to have more descriptive names. Either option is workable, but in my experience with introducing developers to projects, more descriptive names and types lower the barrier to entry and reduce the amount of guidance the current developers need to provide.
Cheers, Zach
-- 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
