Last month I talked about how my min and max template functions do not work when one argument is const and the other is not. The point of the diatribe was that sometimes nothing works as well as reverting to old habits, in this case the use of a #define macro. The behavior that caused the problem is that exhibited by Borland's C++ 3.1. I ran similar tests against Watcom C++ and did not have those problems. I cannot tell you which compiler is correct, because I do not know what the ANSI C++ standard will say when it is published sometime in the next century. Borland's version 4.0 with its nonsensical no-nonsense license is out, but Ihave not yet installed the shipping version. If you have not heard about the license, you should know that it attempts to restrict the types of applications you can write (no operating systems or databases, for instance) and requires you to obtain a royalty-free license if you distribute more than 10,000 copies per year of your application. As you might expect, this has ignited a firestorm amongst programmers worldwide. I'll delve into this in depth in next month's column. The beta version has the same problem, and compounds it by including its own min and max template functions with const parameters. Now, the usage works only when both arguments are const. I had to comment out their templates and use my own.
My min and max templates work very well, thank you. I am thinking about patenting them. No? Read on.
Last month's editorial in DDJ told you about the patent Compton's NewMedia received for access to multimedia data-bases. Although the Patent Office has since decided to review the Compton's patent, the implications of that patent and the intentions of its holder are enough to shake the foundations of software developers everywhere. Here's another one, although in a smaller scope. I am concerned about what it implies. Not only might D-Flat's example Memo-pad program be subject to the licenses claimed by the holder of this patent, but so might the products of every major software developer in the country.
Psytronics of Princeton, New Jersey holds patent 4,540,292. I learned about it when an associate received a letter from a lawyer suggesting that my friend's software product, a contact manager, might be subject to licensing by the patent.
The patent abstract describes an "electronic calendar display in which each column always corresponds to a particular day of the week_." According to the patent, all prior-art patents were for devices where the first day of the month is always in the upper-left corner of the calendar matrix, sliding the days of the week around to match the current month. Seeing a need for a calendar display that resembles the real thing, the company designed one, built it, and patented it in 1985.
My friend's contact manager displays a calendar on the screen, similar to the one in Windows Calendar, Borland's Sidekick, Casio Boss, and every other hardware and software product that includes a calendar, including D-Flat's Memopad. I called John Olivo, the lawyer who sent the letter, and asked if he believed that the patent covered software-generated, screen displays of calendars. He said that my question was a complex one but that they had no position on that issue at the moment. I asked many questions about their plans and intentions with respect to the enforcement of this patent as it would apply to us programmers, and he was politely evasive. He would not tell me if they sent similar letters to Borland, Microsoft, or anyone else. He did, however, know about their calendar-displaying products.
Mr. Olivo hastened to assure me that the letter was meant as a friendly inquiry to potential licensees and that my friend should not be concerned. He would not, however, say whether there would be any further legal activity with respect to companies who chose to ignore or respond with an equally polite "no thanks" to their invitation to license the technology.
Perhaps this one has gone as far as it will go. Mr. Olivo told me that Psytronics is a small company. I cannot guess about their intentions or their resources. But the granting of this patent portends a much bigger concern for us. The patent office is handing out patents for so-called inventions that they do not understand, and it seems that anybody can patent anything if it involves or implies software. What does that mean to us programmers? There we sit at our PC, building the next great American application. We use algorithms taken from our own experience and research and from the libraries and literature of the industry. We use them trustingly, never knowing which of them is covered by a patent or a patent pending filed for by a naive "inventor" and granted by an incompetent or uninformed bureaucrat. The application hits the big time. It catches the attention of the dozen or so patent holders who sit quietly and watch patiently for their opportunity. Like parasites, they line up to feed on our revenues. Each one expects a license fee, a percentage of our gross sales. Get caught by enough of them, and the leech percentages add up until we are out of business.
My friend asked what he should do. I gave him the only counsel that I could give, the one piece of advice that sets my teeth on edge and sends shivers up my spine. I told him to call a lawyer.
The task of writing a D-Flat++ programmer's guide is upon me, and I am faced with a common dilemma. How do you effectively document a class library? Approaching this from the view of the user, the programmer who will use the classes, I remember problems I've had reading the class-library documentation for OWL, MFC, and others. They describe the class interface in terms of the public member functions that are in the class itself, making you search up the tree for inherited functions. I sure don't want a hernia from carrying the document from the shelf to my desk, but I need all the information when I need it, and therein lies the problem.
As a class user, a programmer wants to know the nature and behavior of the class's public interface. You are not always concerned about whether a particular member function is inherited, overridden, or unique to the class being used. There are exceptions, of course. If you are dealing with pointers or references to a base class, you need to understand the differences between the behavior of the virtual functions in the base and the derived classes. But, in most cases, you really just need to know how the methods behave in the context of the object that you instantiate.
Reading about the derived class in the typical programmer's guide, you learn about its member functions. Then, you must look at all of the public member functions of all the base classes up the tree to see all of the methods available to the derived object. Class definitions are sometimes presented in alphabetical order, and the search involves leafing through one or more books, holding your fingers, pencil, comb, mouse, coffee spoon, or whatever is handy between the pages to mark your place. Other times the classes are grouped in categories, and you have to do all of the above, plus root through the index and hope that it is correct. In either case, you have a desk and lap full of books with bookmarks sticking out everywhere.
The documents could save you all that book-jumping by repeating the descriptions of all of the base methods for all of the derived classes. Two things would happen. First, you would need a front-end loader to carry the books around. Second, class documentation would get out of sync when base classes changed, particularly if the project suffers from a less than conscientious documentation effort. The usual approach is for each class to document its own methods, so nothing is duplicated. It solves the bulk problem but is less convenient for the programmer, who must search a complex class hierarchy to find all the methods available to an object.
These are the problems of paper documentation, and it makes me wonder why we still deal with paper. Isn't paper finally obsolete? All of the manuals for Borland, Microsoft, and Symantec compiler products now come on CD-ROM along with the software itself. They use effective presentation and search engines to display the documentation on the screen. But they also deliver books, which contain the same information and have no search engines beyond the traditional tables of contents and indexes. Why do they go to the expense of duplicating this information, using up trees, weighing down the mail person's sack, and filling our book-cases? Part of it is our fault. Programmers gripe if the vendor cuts back on documentation, even when the text is available electronically and with an intelligent search engine. We perceive the value of a product to be relative to the bulk of the package. Marketing strategists know this. They like it when the product is in a big box. Buyers are subliminally induced to attach greater credibility to the bigger package. It gets more room on the retailer's shelf and, therefore, more visibility. There is also the belief that products with documentation endure less piracy because the users want the books.
Electronic documentation is a better idea. It weighs ounces. It is more current. (No more README.DOC files to tell us what changed since press time.) You can find things by using intelligent Boolean queries. Electronic documentation can have hypertext links. It can talk, play music, and show video clips. It can include examples that you can compile and run on your computer. You can click on an element in a class-hierarchy diagram and see its interface methods. Click a method and see its description. When a new version of the compiler or tool comes out, your dog can use the old CD-ROM as a Frisbee. Save trees, landfills, and cervical vertebrae.
What is more, a properly designed class browser would group the methods under each class that can use them, regardless of where they come from in the class hierarchy. It would use single copies of the function descriptions, applying them according to the class declarations taken from the same source-code header files that the compiler uses.
As I ponder the business of writing D-Flat++ documentation, I am happy that developers of public-domain software are not bound by the parameters of a market-driven economy. I don't need to, and will not print a manual. At the very least, the document will be a text file. With time, however, I will build a class browser that does what I just described.
Back to the issue of commercial programmer's tools. Ask yourself this. If the Zippo C++ Compiler and Applications FrameUp product came in a mailer with only a CD-ROM and a booklet that says to run SETUP from the Program Manager, would you still buy it? How about at a reduced cost that allows the vendor to recover development costs and still make a profit? What if you could buy the bound documentation as an option? Or in a bookstore? If you would not do any of these things, if you insist that every product and every upgrade comes with all the manuals printed and bound, ask yourself why.
Looking to the 21st century, we foresee an era driven by technology. The White House is on the Internet. The information highway leads directly to the pinnacles of power, and anyone can ride. Astronauts are walking in space, replacing the Hubble's 80286 with a 386, fixing things so that we can see to the edges of the Universe. Up and down Silicon Valley, programmers of compiler tools are chiseling out new and innovative ways for me to add sculptured radio buttons to my cold-steel, shaded, sculptured, three-dimensional dialog boxes. These are exciting times.
I'm living this week in the heart of the Valley, having come to spend some time in the editorial offices of DDJ. This is where the guardians of the future of our technology live, work, and shape our lives. I should be exhilarated just to be here where it all happens. At first I was.
Then I tried to make a telephone call from a Best Western motel room in San Mateo to a residence in Los Gatos, about 40 miles to the south.
The phone in the motel room has an insert with printed instructions for using a credit card. Dial 9-0, then the area code and phone number, it says. I do. After several clicks, beeps, rings, and other electronic R2D2 sounds, an operator comes on the line. How may he help me? I want to charge this call to my credit card. What number are you calling? The one that I dialed. Would you tell me what it is? I do, and he asks for my credit-card number.
I should have been suspicious. Back East, you don't have to talk to these people. You dial the way you are told, the phone goes "boing," and you dial the card number. "Thank you for using AT&T," the synthesized lady says, and the call goes through. When you involve the real people, the rates go up. No matter, I told him my credit-card number. Sorry, says he, I can't bill to that credit card. Why not? It's for a different carrier. Yeah, says I, AT&T. We are a private carrier, says he, and you will have to call an AT&T operator.
The phone's instructions say to dial 9-000 for AT&T. I do and get an AT&T operator, a real person again. I repeat the drill, and the phone goes dead. I try again and tell the new operator what happened. She promises to stay with me for the duration. I repeat the phone number and credit card number for the third time. "Sorry, I can't place this call." What? Is my card invalid? No, your card is fine, but I can't place the call to that number. Why not, is it a local call? No it's a long-distance call, but it's not long distance enough. That, dearhearts, is a direct quote. Here I am, says I, with a telephone in one hand and an AT&T credit card in the other, and you won't put the call through; what can I do? Her supervisor comes on the line. Now I have a person with authority. Call a Pacific Bell operator, he says, they can bill to your AT&T card. How do I get them? Dial 9-0.
I dial 9-0. The operator answers, and I start over again. Sorry, says he, I can't bill to that number. It's déja vu all over again. Are you a Pacific Bell operator? No I'm a CTS operator, and we are a private carrier. How do I get a Pacific Bell operator? Dial 9-0. That's how I got you! May I suggest that you call your motel operator for assistance? You may.
The motel operator listens patiently. She has, she says, heard this story many times. No, she does not know how I can get a Pacific Bell operator from that phone. She herself uses Pacific Bell at home and cannot make a long-distance call from the motel. She doesn't know how things got to be that way. We decide that I should walk to Denny's and use the pay phone. It's raining today.
Somewhere in this fabled land Judge Greene, having retired and left the bench, has no further use for the telephone and its conveniences. He treasures his place in history, though, because he is secure in the knowledge that he performed a vast service for his country by breaking up the finest communications system that the world has ever seen or will ever see.
Copyright © 1994, Dr. Dobb's JournalPatently Absurd
Creative Bookmaking
Where is Don AmecheNow That We Really Need Him?