At 11:57 AM 6/25/2008, Frank Brickle wrote: >On Wed, Jun 25, 2008 at 7:09 AM, Jim Lux ><<mailto:[EMAIL PROTECTED]>[EMAIL PROTECTED]> wrote: > >I hate to fall back on the "read the source code" trope, because I >genuinely believe that source code is a terrible way to document >interfaces, but, as it sits, that's all there really is. > > >The "read the source code" trope has yielded at least six working, >sophisticated spin-off SDR projects. By any empirical standard, the >argument against it has to be regarded as temperamental and >speculative, not substantive. In other words, it's an easy criticism >to level, but it has few correlates in the real world. The >counterexamples are enough to show the flimsiness of the argument.
My comment was NOT that "read the source code" isn't a way to create spin off products, but rather that it is a poor way to document interfaces. I will also readily concede that knowledge of the interfaces is not a necessary condition to create new stuff. Interface descriptions, though, are a way to bring about wider acceptance and familiarity. I would say that we greatly benefit from interface standards such as RS-232 and the PC-Parallel Printer Port, and, in fact, the without the latter, the SDR1K would likely not have existed. If one has a desire to document interfaces or consume such documentation(and I grant that this may or may not be true for any particular person), neither a bare recitation of the interface specifications nor a working example alone do a good job. Inevitably, the bare recitation of specifications(if of reasonable length) cannot be complete enough to explain all side-effects and preferred usage. (e.g. if you read the AD9854 data sheet, you know how to program the DDS at the register level, but that doesn't tell you much about how the system that the 9854 is in will work, nor what a "good" sequence of programming instructions is.) Likewise, the working example provides only a single instance of the interface usage that works, and doesn't tell you much about what won't work. If you want to go beyond what's in the example, it's nice to have some guidance. (To take the AD9854, if you only had PowerSDR to look at, you wouldn't know that it's possible to adjust the phase of the DDS independently, because that function is never used, and not exposed in the include files or API calls) Particularly in integrated systems, there's a lot of subtlety in making it work that isn't always in the data sheets, or the data sheets don't even exist. The timing of the PC parallel port and the latches in the SDR1K, in connection with Windows's assumptions about how printers work, is a fine example. (otherwise, we wouldn't be worrying about whether a particular USB/Parallel adapter works) There's also the documentation aspect of defining "currently unused, but you shouldn't use them" aspects. The source code for the F5K interface gives you a fair amount of information about the MIDI messages that ARE used to control the F5K, but not much, if anything about ones that shouldn't be used (or, even, if there are such things.. maybe the F5K is robust and ignores things that don't make sense).. And, then, the source code doesn't tell you much about the structure of the calibration parameters stored in the F5K and how they work, without having to fully understand how the calibration process works, how the software interaction between dttsp and the F5K works, etc.. One might argue that nobody really *needs* to know this, and if you do, you can figure it out with a bit of work and some good guesswork, and some test equipment. There might also be a regulatory reason to keep it a bit opaque. On the other hand, this makes it pretty tough to write a good replacement for PowerSDR, because a replacement would have to duplicate most of that functionality, and your replacement might not have a similar enough architecture that you could just wholesale borrow the code from PowerSDR as a "black box". You're also going to have to live with the risk that Flex could up and change the way things are done, roll out a rev to PowerSDR that is compatible with the new way, and you'd be stuck looking at the new software trying to figure how it differed from the old software. On the other hand, if there were a published interface description, it would likely be shorter and more concise, and understanding what changed would likely be easier than looking through dozens of changes in thousands of lines of code and figuring out which ones are relevant and which ones aren't. It is the "database import/export" problem in spades, eh? Jim, W6RMK _______________________________________________ FlexRadio Systems Mailing List [email protected] http://mail.flex-radio.biz/mailman/listinfo/flexradio_flex-radio.biz Archives: http://www.mail-archive.com/flexradio%40flex-radio.biz/ Knowledge Base: http://kb.flex-radio.com/ Homepage: http://www.flex-radio.com/
