Principles of Software 2 Now that we have the basic idea of how to make sense of a program written in C, and have understood the basics of programming, we need to develop the ideas further to see how these ideas apply to a wide range of software situations. In addition, we want to look at how to create specialized software documentation for APIs and SDKs. ACQUIRED KNOWLEDGE AND SKILLS In this lecture, you will learn the following: • Principles of Object Oriented vs. Procedural Languages • How to write API Documentation • Software Development Cycle Procedural vs. Object Oriented Programming In the last lecture we learned that a programming language like C consists of two main components: Data and Instructions. For a quick review consider the following. DATA Single values called variables. For example int age; float temperature; char grade; Groups of values with the same data type, called arrays; for example: char name [15]; int scores [10]; Groups of values without regard to data type; for example: Principles of Software and Programming Copyright ©YEDA 2006 2 struct Employee_record { char name [15]; int age; float: salary; int years_with_company; }; INSTRUCTIONS These consist of programming statements and groups of such statements (functions). PROCEDURAL LANGUAGES Because the structure of a C program is such that it divides the world into data and instructions (functions) that do something with the data, it is called a procedural language. That is, it tends to look at the world as a collection of activities. Although this approach works well for things like business or industrial processes, it becomes less intuitive when trying to construct programs that control complex interfaces with many components. For example, think of the Windows operating system and interface. Although you can think of it as a collection of activities such as displaying windows, opening and closing windows, etc., it is more intuitive to think in terms of the components themselves: windows, toolbars, menus, etc. OBJECT ORIENTED PROGRAMMING Object Oriented Programming (OOPs) was developed to help solve this problem. Data and functions still exist in the Object Oriented approach – but they are contained in what are called objects. An object is just what it sounds like – some “thing” that you can recognize and manipulate in some way. For example, in the Windows interface, an object might be a Window, a dialog box, a toolbar, or a menu. In the “real” world it might be a physical object like a table or a chair. In any case, when you think about it, you begin to realize that to fully describe an object, you have to think about more than just what it looks like. Thinking in slightly more abstract terms, we can say that any object consists of data such as its dimensions, color, weight, or whatever else defines it; and the different activities that it can perform – i.e. functions. For example, a dialog box may have a certain size, color, and location; but it can also participate in Principles of Software and Programming Copyright ©YEDA 2006 3 various activities such as opening, closing, and being moved on the screen. All of these – the data and the functions – make up the object. In terms of programming, you can think of an Object as a mini-program, a program within a program. In some ways, it’s kind of like a super struct, a unit with various kinds of data, together with functions. Besides making it psychologically easier to create programs for various situations, object oriented programming also make programs easier to read – data and functions are contained in units called objects, and once an object is defined, you can use the name of the object in other places in the program without having to write out all the data and functions again. CLASSES AND OBJECTS The idea of an object goes hand in hand with a more abstract concept called a Class. A Class is a kind of template or definition that will be applied to particular concrete items, which we call Objects. For example, if we are programming a Window, the general definition of Window would be the Window Class. This might consist of data that describes a window’s size and color, as well as the various activities that it can perform (being moved, opening, closing, etc.). Once we define the Class, we can create a specific window, say the Main Window, and assign various values to the data and functions defined by the class. For another example, suppose we were programming a game in which we had various animals. We might declare a “dog” class that looks like this: class Dog { private: int age; int weight; public: Dog(); //Constructor ~Dog(); //Destructor void bark(); }; Here we see that the dog class is made up of data such as age and weight (these are declared as integers) as well as some activities (functions) that are associated with the object such having the dog “bark”. A few things to notice in the above declaration section: The section is divided into private and public declarations. The private ones are those that can be accessed only by the class itself – that is, the variables and functions are for internal use of the class and can’t be called outside the class. The public variables and functions can be used or called in the main part of the program. Variables in a class are referred to as “properties”. Constructor and Destructor functions allocate or release memory resources for objects created from the classPrinciples of Software and Programming Copyright ©YEDA 2006 4 The void data type is often assigned to functions to indicate that the function does not return a particular value. The constructor function enables the compiler to allocate memory resources to create the object that is based on this class; the destructor function (indicated by the ~ releases these resources when the object is no longer used). Comments in C++ are indicated by slashes //Notice that we still have not defined what the “bark” function consists of. We can define or modify the functions that make up a class by using a double colon notation like this: Dog::barks ( ) { getsoundfile(); play_sound_file(); } This just means that the function “barks” is itself made up of two further functions, getsoundfile and play_sound_file. Of course, these functions themselves have to be defined somewhere, perhaps in a library of functions, or maybe later in the program itself. Typically, object oriented programs use libraries and other files where the functions are fully defined – then, in the program itself, we can just call the function without having to see it’s “insides”. This helps keep the program short and easy to read and allows us to use a wide range of functions from various sources. Inheritance A useful feature of Object Oriented languages is the idea of “inheritance”. This refers to the fact that we can create subclasses (called derived classes) that inherit the properties of the base class. For example, in our Dog examples, suppose we wanted to create a Poodle class that inherited the properties of the Dog class. We could write the following: class Poodle : public Dog { public: int color; int times_it_eats_a_day; void squeaks (); }; Objects created from the Poodle class would inherit all of the Public properties and functions of the Dog class, in addition to the specific properties and functions of the Poodle class. Private properties and functions are NOT inherited. Principles of Software and Programming Copyright ©YEDA 2006 5 Exercise 1: Creating a Class Create a Class that represents a simple (minimal) Cmap. Make sure that you include all necessary components, including functions (activities) that pertain to it. Try to write the Cmap class in terms of C++ code like the Dog class above. Using Classes and Objects Once a class is defined, it can be applied to an object very much the same way a struct can be assigned to a single member. For example, we could create an object called Fido like this: Main ( ) { dog fido; } For a more interesting program, we can assign Fido an age like this: Main ( ) { dog fido; fido.age = 2; } Here, we’ve used a “dot” syntax to assign 2 to Fido’s age (remember that according to the dog class, Fido has an age and a weight). This is the same syntax that we used for assigning values to variables in a struct. Exercise 2: Documenting a C++ Program Write comments explaining the program at this link: http://functionx.com/cpp/examples/simpleclass.htm Principles of Software and Programming Copyright ©YEDA 2006 6 API Documentation Often, technical writers are called upon to document what is called an API. This stands for Application Programming Interface and is a set of classes and functions that deals with the interface between a software program and an operating system. For example, Windows is an operating system that handles the computer operations of a PC. An application that is written for Windows must take into account how Windows operates and must use certain standard windows functions, classes, etc. in its program – otherwise, it simply would not run in Windows. Many programs have their own API functions. This enables other developers to connect these programs to other systems, for example, to databases, or to specialized interfaces. One of the tasks that technical writers find themselves doing is writing documentation for an API. This consists of the following: General material including Introduction and Overview Command Reference documenting each function (i.e. command) Let’s look at what you need to write for each of these parts. WRITING THE INTRODUCTION The Introduction is not different than any other introduction that we’ve already learned to write in Lecture 6. You provide a paragraph about what the API consists of and what it allows you to do. It can be as brief as the following paragraph from the online Google Maps API: The Google Maps JavaScript API lets you embed Google Maps in your own web pages. To use the API, you need to sign up for an API key, and then follow the instructions below. The API is new, so there may be bugs and slightly less than perfect documentation. Bear with us as we fill in the holes, and join the Maps API discussion group to give feedback and discuss the API. Short and sweet! Of course, for some programs, especially if you have a hard copy document, you’ll want a page or so, with a bulleted list indicating the various features/benefits that the API gives you. Here is a longer introduction from an API for software that runs a call center (http://www.call-centerteechcom/ivr-software-manual.htm): Principles of Software and Programming Copyright ©YEDA 2006 7 IVR Library Functions and Features Database Systems Corp. (DSC) provides an API library of IVR routines. An IVR application functions in a client/server environment, where the controlling program for the IVR can run on the phone system or on the same server as your application programs. The IVR program now has complete access to all of the same information as your applications, so it can actually perform call center functions such as dealer lookup, account information access and update, etc. and simply transfer the result information to the our phone system to be relayed to the caller. Some of the basic features of the our IVR system are: • Client/server architecture • Visual Basic, C, C++, Active-X, and .NET support • VoiceXML data access • DNIS controlled • Inbound and outbound call processing • Record messages • Play music on hold • Multiple IVR scripts • Play message and prompt • Play mixture of recorded message and text • Phone key input • User navigation and selection • Voice mail • Database access and update • Text to speech (TTS) • Perform application functions • IVR response logging and reports WRITING THE OVERVIEW The Overview is more complex (as we already know). But, like the Overview for a User’s manual, the API Overview has the same basic content: an explanation of the major conceptual ideas on which the API is based, and a kind of “tour” of the system. In this case, the “tour” will consist of code Principles of Software and Programming Copyright ©YEDA 2006 8 examples showing how you can do different things with the API code that might interest programmers. The Overview should start out by again explaining, in more detail than the introduction, what you can do with the API. Once the major points are explained, you may need to show how the API functions are organized – functions and classes usually fall into broad categories which should be explained from a general, conceptual point of view. The following example is from the above call center API. It is actually shorter than the Introduction and so is far from complete: How Our IVR Works Upon receiving a call, the DSC phone system uses the DNIS to check for an IVR script. The IVR Client process invokes a server process on the application server and starts a two-way communication with the IVR Server. An IVR program controls the flow of the IVR script by prompting the caller and requesting key input or directing the caller to another DNIS, extension, or Voice Mail. In the process, this IVR program can perform any application function including report generation, customer information lookup, etc. Our IVR can also initiate outbound calls and prompt the called individual with the same messages (and text) and accept phone key input from this individual as well. The caller and called individual can likewise be “connected”. IVR Administration The DSC phone system includes a setup window for IVR scripts. Upon definition of a DNIS entry, the administrator can designate that callers on this DNIS will be automatically routed to an IVR script. There are several problems with the above Overview: It needs more explanation of each of the items mentioned: IVR script, IVR Client, etc. It needs some diagrams that show the processes described verbally. It needs examples of scripts, sample code, etc. as we described above. Click on this link to see a well written, detailed API Overview: http://developer.ebay.com/DevZone/XML/docs/WebHelp/wwhelp/wwhimpl/c ommon/html/wwhelp.htm?context=eBay_XML_API&file=InvokingWebServi ces-Overview_of_the_API_Schema.html The above Overview is for an XML based API (XML is the same language that we learned about in the Single Sourcing lecture). It is for developers of programs that are intended to work with ebay. The Overview contains three essential ingredients for a well written, clear API Overview: Principles of Software and Programming Copyright ©YEDA 2006 9 Summary sections that clearly show the reader the major categories that make up the API. This helps put a long list of commands into some kind of perspective. Diagrams that illustrate the structure of the API and its relationship to the activities that the developer wants to produce. Examples, especially actual code examples – for programmers, this is the most important ingredient. Here is an example of the first point – a clear summary: Overview of the API Schema This section introduces the major components that are available in the API schema. The schema is organized into these major components: • API request and response messages (see Message Types) • Core components (see Core Components) • Base components (see Base Components, Data Validation, Code Lists) Notice that each of these categories is given a link so that the reader can jump to more details. Here is an example of the second point – illustrations and diagrams: Finally, here is an example of the 3rd point – code examples: Principles of Software and Programming Copyright ©YEDA 2006 10 CORE COMPONENTS Certain constructs, such as monetary amounts and units of measure, always require the same combination of elements in order to be semantically meaningful. For example, a monetary amount is typically modeled as a currency and a value. Various base components use amounts represent notions like listing fee amounts and account balance amounts. We define the types such as amounts as core components in the schema. Example 5-1 is a snippet from the FeeType schema and shows that the FeeType component consists of a name (a string describing what the fee is for) and a fee (e.g., USD 1.00). The fee is represented as an amount type, Example 5-1 Definition of a Type that Uses a Core Component (XML Schema) Exercise 3: Writing an API Overview Although we can’t write an Overview of an API that we really don’t know, we can suggest changes to the Overview and place requests for information at various places in the document. Rewrite the IVR Overview on page 8 above; you can review the list of functions (contained in the Table at this link: http://www.call-center-tech.com/ivr-software-manual.htm) to better understand the API. Although you probably won’t have enough information to write a full Overview, write as much as you can, and indicate where you need diagrams, examples, etc. and what other information you may need to complete the Overview. WRITING THE COMMAND REFERENCE The last part of the API manual, and the main part, is the Reference section. This consists of a list of commands (for example, functions in C++, or Methods in Java) and includes the following: Name of the function Brief Description Syntax Parameters (description of each) Return value (what the function returns after it is finished processing) Example Here are some examples of this type of documentation: http://msdn2.microsoft.com/en-us/library/ms644982.aspx http://msdn2.microsoft.com/en-us/library/ms647990.aspx Principles of Software and Programming Copyright ©YEDA 2006 11 These examples are from Microsoft’s MSDN (Microsoft Developers Network), a very comprehensive site that provides information on all the functions that programmers need for creating Windows programs. Although the brief descriptions are written in this way: The LoadMenu function loads the specified menu resource from the executable (.exe) file associated with an application instance. The more accepted way is to keep the description even more concise by starting with a concrete verb like this: Loads the specified menu resource from the executable (.exe) file associated with an application instance. For the Parameter section, the parameters are generally arranged in a 2 column table: parameter, Description. Note also that each section has a clear title, i.e. Description, Syntax, Parameters, Example, etc. How should you arrange the functions in an API Reference Section? The best way of arranging commands (i.e. functions, or methods) is alphabetically (as Microsoft has done in the MSDN). Alternatively, if there are clear groups of commands, you can arrange them alphabetically in separate chapters. In either case, you should provide a brief Overview in which you list the functions by group or category so that programmers can find what they’re looking for. Exercise 4: Do cumenting an API Function Assume that the following API function is contained in the Dog class: Bark (int pitch, int volume); Use your imagination and write standard documentation for this function. Use the patterns that you observed in the API examples above (at the various links). Principles of Software and Programming Copyright ©YEDA 2006 12 DIFFERENCES IN TERMINOLOGY Although this lecture cannot go into the exact differences between programming languages, it should be clear that the most popular languages today: C++, Java, .Net, and C# are all based on Object Oriented approach and the actual code syntax is basically C or C++. There are some differences in terminology that you should be aware of, however, when documenting functions for APIs written in these languages: In C++ we have functions. In Java these are called methods. When referring to a function, we have parameters (the variable data that the function takes). For a Class, we have variables too, but they are referred to as “properties”. In .Net, variables in a class are called “fields”. The “functions” in a class are referred to as functions (C++), or methods (Java). A package in Java is basically a Class library in C or C++ (just like functions, classes can be contained in libraries too). An “interface” is a Class that is never really used. Instead, it stipulates that any other class that is based on this one (i.e. a derived class that inherits from the interface class) must contain all the properties and functions of this class. In other words, if we have a class called Dog that defines what a dog should look and act like, all other classes such as Poodles or Beagles, MUST contain these same properties and functions. This ensures that all dogs have basic characteristics in common – they all have to bark, they all have weight and age, etc. The interface Class constrains the programmer to adhere to certain basic definitions when constructing classes and their objects. Principles of Software and Programming Copyright ©YEDA 2006 13 The Program Development Cycle The development of a software program requires a great deal of planning -companies cannot just start writing a program without preparation. The prescribed method for software development is shown below -unfortunately, not all companies strictly adhere it (which may create problems for the company later on). Stage Description Requirements Discusses financial issues and feasibility: staffing, resources, project costs, and schedules. Specification Defines what the program does, the interface, how to work with the program, etc. Technical communicators can often use a spec to gain valuable information about the system. Design Specifies the high level modules and their interaction. Defines the algorithms. May specify sub-modules and functions in program. Documentation (Internal Doc.) Explanations of the functions so that others can understand the program. This is supposed to be written by the programmer, but sometimes a technical writer can be brought in to edit the material; in rare cases, a writer is brought in to sit with the programmer and help write the internal comments. Coding The actual program code in a particular programming language. Debugging Finding mistakes in the program: -Compiler errors -Run-time errors Testing Test the program to see whether it conforms to the original specifications. Maintenance Continued testing and debugging. Also, enhancements. Technical writers can be brought in at any of these stages. Typically, though, the writer is brought in near the end of the cycle when the program is being tested and ready to be released. This, of course, puts pressure on the writer to finish the work quickly so that the product can be released to the public. Ideally, the writer should be brought in as early as the specification stage so that the writing can develop along with the program – this ensures that the Principles of Software and Programming Copyright ©YEDA 2006 14 writing is more complete and accurate, and that the document goes out on time as well.