William "Chops" Westfield wrote: >> 10 line subroutines > > Throughout this discussion I've seen "code can't lie like comments can", > ... I don't think anybody has written this in this thread. > ... and it seems to me like this isn't really true. It isn't; you're right. What is true (IMO, of course) is that it is less likely that a function name gets out of sync with what the function does than the header comment of the function getting out of sync with what it does. That's all there is to it, but IMO it's powerful. Especially when you try to get into the habit of giving your symbols meaningful (consistently meaningful) and specific names. > By the time you get to the depth of function calls implied by 10-line > subroutines, I think the obvious string of self-documenting function > names can actually lie quite a bit. But you can work on this chunk by chunk. If you look at such a 10-line function, it's usually relatively obvious whether the function name lies or not. If it doesn't seem to be clear, find a better description. If there isn't a good descriptive name, there's a good chance that your design is somewhat off. > You're assuming when you look at such code that the lower level of > functions is debugged and working, which may or may not be true ... Right, of course. The devil may be everywhere. It's not about bug-free code, it's about reducing the likelihood of bugs and about reducing the time to find them. I think 10-liners are a bit on the extreme side, but IMO functions that don't span much more than a single screen height make debugging a whole lot easier. (And this is completely independent of the overall complexity of the system... works for me as well in one-day programs as it works in programs that contain dozens of man-years.) For the last few months I've worked over some (C++) code that I inherited. It was almost impossible to understand, and the comments didn't help much. It's now a reasonable construct of reasonably short and clear functions -- and guess what, it works better and is /much/ easier to expand. > ... (just like the comments may or may not match the actual code.) "Just like" in the sense of possibility, but not in the sense of probability. Again, it's not about getting all the black out and creating something purely white, it's about getting the grey as clear as reasonably possible. > I'm sure I've done this many times. Spent hours staring at a function to > try to figure out what was wrong with it, only to eventually realize > that the actual problem was in a lower-level function that I was > "trusting" to work in the obvious way. Well, you shouldn't trust, in such a case. (You probably know this :) This of course can happen with long functions and with short functions. The question is not whether or not, the question is what helps you reducing the likelihood of it happening and what helps you reducing the time to find and fix it. > (similarly, I have occasional doubts about the "avoid numeric > constants" rule in most C environments. If there is code like: >> for (i=0; i> enqueue(interface_info_queue, malloc(INTERFACE_DATA_SIZE)); > whether this is "reasonable" or not to me as a code reviewer depends > substantially on the actual values of NUM_INTERFACES and > INTERFACE_DATA_SIZE, and sometimes figuring out what those are > involves diving down through multiple layers of stuff (#define > NUM_INTERFACES (NUM_ETHERNET+NUM_SERIAL+NUM_ASYNC), #define NUM_ASYNC > (NUM_ASYNC_PAS+N_AUX_LINES+N_VIRTUAL_ASYNC), #define N_VIRTUAL_ASYNC > PLATFORM_MAXVTYS, ...) If the loop is allocating 1000000 10-byte > blocks, or 10000 10000-byte blocks, those are both not-so-good, for > different reasons, but I CAN'T TELL! Grr.) You may need a better editor. It may be a pain to collect all those pieces, and it may or may not be badly designed (I don't think anybody ever claimed that short functions is a reasonable replacement for good design :), but it shouldn't be farther away than a few right clicks or hover-overs or whatever your editor needs to get you to the definition. If it is actually so complex, a numeric constant wouldn't really cut it either, because you'd have to change it whenever you change any of its dependencies -- now that would be a mess, it seems :) Gerhard -- http://www.piclist.com PIC/SX FAQ & list archive View/change your membership options at http://mailman.mit.edu/mailman/listinfo/piclist