From: Eric Schwartz Date: 2005-04-29T04:49:32+09:00 Subject: Re: Comments Are More Important Than Code "Dave Fayram" writes: > James Britt wrote: >> If first I write >> # This should check that a given user name does not exceed >> # a max length because of reason foo >> >> and that convert that to code, have I done "up-front" design? >> >> Perhaps. > > I'd much prefer to see (this is pseudo and formatted for short lines, > so bear with me): > > def my_appropriately_named_test > long_name = "This name is far too long." > assert_raise Module::InputValidationError, > @inst.the_func( long_name ) > end > > Then I can test it. If I ever make a change and accidently invalidate > it, then I'll know. If we ever eliminate that restriction, the test > will break and we'll know to update it. How will you know if it's the test or the code that's broken? Without comments in the_func telling you why that exception is raised, you could end up fixing the wrong problem. A not-uncommon case is that you have to call into a 3rd-party C or C++ library (the infamous Jukebox example in Pickaxe 1, for instance), and that library enforces some restrictions that aren't necessarily obvious. Let's say we have implemented the infamous Jukebox application only supporting ASCII song titles, and we now want to add support for UTF-8. Since it's been some time, and the original coder has moved on to another company, we've forgotten that libjukebox doesn't work with, say, UTF-8. If I had a comment in the_func saying: /* libjukebox can't handle songs with UTF-8 encoded titles */ raise Module::InputValidationError if has_utf8?(title) That helps me a lot more than just: raise Module::InputValidationError if has_utf8?(title) In the latter case, I might just think, "Okay, they didn't want to support UTF-8 in revision 1, so now i can take it out." In the former case, I know *why* they didn't support it, and it wasn't because they were lazy, or pressed for time. So instead of removing the code, and its associated test, I know to ask Jukebox, Inc. for a new library that does support UTF-8. -=Eric -- Come to think of it, there are already a million monkeys on a million typewriters, and Usenet is NOTHING like Shakespeare. -- Blair Houghton.