James Britt wrote: > Maybe. Certainly, running code is no proof > of anything other than that the code runs. Which is more proof than anything documentation an ever give you. I can provide a pile of documentation for you. It proves exactly nothing. It does exactly nothing. Without code, the documentation is worse than worthless. Which is not to say that it's worthless when coupled with code. > Writing out the intent and goal of some class or method > before writing the code may help the developer clarify > his or her thoughts, such that the code may be more likely > to be written correctly. So can unit testing. And unit testing is repeatable. And it lets you know when it's no longer correct, because the test will break. > In the end, you have to have a clear understanding of what the code > should be doing. Comments can help. I never said comments were bad. Please stop trying to force me to maintain a position I never intented (nor intend) to take. I'm all for documenting and commenting your code. I feel that the extremist approaches, as given in that article, are steps backwards and not forwards. Did you read the article? Did your realize what he was really suggesting? > Interesting. This sound like, "Just code, don't design at all." No. It's not. The fact that you think it is is telling to me. It's a common extreme programming idiom to start coding and getting into iterations quickly. I have no inclination to redundantly spout its justifications when a perfectly good piece of literature exists on the subject. Part of the algile methodology is to cut down on extraneous products so as to help prevent that exponential-cost curve that we see so often when being told the benefits of the Waterfall Method. > 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. > Would creating CRC cards be up-front design? > Would that make them bad? CRC cards do not exist at this level. They are extremely high level abstractions and once the code is written, you can throw them away. They are not expected to be more than a way of capturing your rough thoughts about the project. Please, stop trying to pigeonhole me into a position I didn't take. > I prefer to decide what the code does, not let the code decide for > itself. Comments-before-coding are similar to sketching in a drawing on > canvas before doing a large painting. No doubt, as a work develops, > things will have to change, but that doesn't argue for the elimination > of the entire sketch. I'm not going to argue that your way of being productive is bad. I am going to argue that making the default entry mode in a file of source code the comment mode is crazy. I'm not going to argue that a little bit of sketching and writing and even commenting up front is a bad thing, because I don't believe that. I do believe that excessive use of this technique will lead to inaccurate comments and possibly lead people to believe they don't need unit tests. > Same goes for writing unit tests that test the wrong behavior. I see > comments as a way of helping ensure the developer is clear on the end goal. I find them to be troublesome. But as long as we aren't seeing excessive amounts of comments, aren't substituting them for good unit tests, and not using them as an excuse to get away with bad code, then I'm fine with them. I just believe that they are, and forever will be, secondary to good code and good unit tests. > > Oh, and we had a readme explaining what the code did at a higher level > > (*cough*techmemos*cough*). > > Does that doc lie? Was it written to define the intent of the program > prior to coding, or written to explain whatever the code ended up doing > after development? It was written to explain the state of the document at release time. This happened 3 times during the life of the software. We also kept a CHANGELOG and TODO file. So it's far more likely to be accurate, since we had the code up front and then wrote about it. Sure, it's a bit of a hassle to maintain a good readme file, but obviously it's important and helpful to do so. > That's too funny. Blame the user. This is the sort of thing that > makes Rails-rooters so endearing. Grow up. I'm not blaming you. I'm suggesting that there is yet more to learn to achieve comfort with the framework. Sheesh.