From: Terry Poulin Date: 2007-09-05T07:44:56+09:00 Subject: Re: Embedded vs. Non-embedded Tests Rick DeNatale wrote: > On 9/4/07, Trans wrote: >> >> >> On Sep 4, 12:07 pm, "Rick DeNatale" wrote: > >> > Personally, it just feels right to me to separate the test code from >> > the code under test, most test equipment belongs in the garage instead >> > of the trunk of the car. >> >> Interesting analogy. We do put some gages right on the dash. But >> that's more like embedding the tests directly into code --eg. rescue >> and try clauses. So maybe you're analogy is a good one. I can see some >> reasons for doing so, it certainly make it easier to send some one a >> test, that they can try against their own implementation, for >> instance. But then I start to wonder about API documentation too. >> Should that also be separated out into dedicated files? Why tests but >> not docs? > > Well , it probably seems more obvious to most to put the doc with the > code (assuming that there is any doc ). Note that we've just now > seemed to get tools like dcov. > > It's long been pretty standard process to have tools which extract doc > from code. On the other hand there are some arguments for keeping > even these two separate. In "The Psychology of Computer Programming" > Gerry Weinberg talked about the trap of "debugging" the comments > instead of the code, and advocated tools which would not just extract > code commentary but REMOVE it. > > On the other hand without having the doc with the code and tools like > rdoc we'd probably have even less documentation than we do now, just a > guess. > > -- > Rick DeNatale > > My blog on Ruby > http://talklikeaduck.denhaven2.com/ > > One thing I am a fan of is reading over my changes at the end of a session and updating to-do lists, especially when it reminds me clean up my comments and rewrite quick-fixes to proper code the next day ;-) It's generally my opinion that the comments tell you what it does and the code how (with comments for the less obvious). If the comments fall out of sync with the code, the comments should be updated once the code is less likely to change to much. Personally I think documentation about using the program should be separate from the regular source code. Documentation about working on the program and it's sources should be kept near by. Just how much, is a matter of developers tastes. I advocate people using common sense, that is to us the gray matter approximately three feet above their romp roast. TerryP. -- Email and shopping with the feelgood factor! 55% of income to good causes. http://www.ippimail.com