Understanding O.O.P. Documentation in .Net
By David M. Woods
Published October 13, 2006, 1:47 pm in Software.
If you're just starting out with Object Oriented Programming (OOP), chances are the first coding you will do will be to create apps out of classes that someone else has written. In essence, you are the "end user" of OOP development software. This software will probably be accompanied by documentation written by its author, usually in electronic format. The documentation, although it may contain a wealth of valuable information about the software within, will likely be rather terse, arcane, and frankly, quite difficult to comprehend for OOP newcomers.
Meanwhile, all the books and tutorials on how to do OOP are heavily-laden with instructions on how to write classes and other OOP elements. As an object-oriented programmer, you will, of course, need to know how to do this. But becoming a writer of classes comes later - first you need to be an adept reader of classes! And in this area, many of the books and tutorials just don't give enough attention.
This article will attempt to break down the mysteries of OOP documentation, and show how to convert those arcane class member descriptions we call "signatures" into real live app code. The development platform will be .Net.
Introducing Signatures
A signature is a very abbreviated yet information-rich device for explaining to you, the OOP programmer-user, how to use a specific API element. (That stands for Applications Programmer Interface, a fancy term meaning "programming language.")
There are two basic ways to document an API: signatures, and syntactical diagrams. A syntactical diagram (SD) might look like this:
Variable = ObjectName.MyMethod(size, category);The purpose of a SD is to show what the code will actually look like. As in the above example, SDs usually contain different fonts to indicate which parts of the code are to be entered exactly as illustrated, and which parts the programmer is expected to substitute with his own names and values. In the above, italic font indicates where substitution applies. SDs are used extensively in tutorials, code examples, and other "how-to" articles. They are fairly easy to understand and use.
But as a tool to communicate to the programmer the important details on how to use OOP elements in a tight, concise, unambiguous form, syntactical diagrams fall short. They just don't contain enough information. For this reason, the Signature became the universal OOP documentation standard, for all programming languages. A typical signature looks like this, in C# :
public int MyMethod (double size, string category)Here's the same signature in VB:
public function MyMethod (size as double,category as string) _
as integerThis signature describes to the programmer-user a class member called MyMethod. We know it is a function or method mainly because of the parenthesis (note that the VB version reinforces this via the keyword "function"). The signature tells us that the function/method requires two input parameters: the first one a double-precision number, the 2nd one a string. The words "size" and "category" are parameter names. You, the programmer-user, are not required to use these parameter names; they are included in the signature to give you a rough idea of what the two input values represent. The signature also tells us that the function/method returns an integer. Finally, the signature contains an access modifier, in this case "public", which means that the function/method can be called from any hosting program.
There is much more information that signatures may also contain. It is usually found in keywords adjacent to the access modifier, and the whole set of these keywords is generically referred to as "modifiers". A fairly complete list of modifiers is given below in the "Reference" section.
Before we start writing code, let's review our available tools.
Documentation tools in .Net
The Visual Studio .Net IDE (Interactive Programming Environment) includes some excellent tools for viewing OOP documentation and researching how to do something.
Object Browser. This tool should be your best friend. It's basically a .Net Framework documentation browser. To view it, go to View -> Other windows -> Object Browser, or just click [ctrl]-[alt]-J.
Everything displayed in the Object Browser has an icon. For a list of icons and their meaning, click here.
There are four panes. (All panes can be size-adjusted by dragging their borders.) The upper pane includes those all-so-important search binoculars, where you can search for anything. There are also a couple of drop-downs to control which order the two main panes display their information.
The left pane is entitled "Objects", and includes a vast assortment of things created by Microsoft, you, or any other programmer who has authored anything OOP-compatible. (See the "Reference" section below for a list.) All objects in the left pane also have an expand-collapse button. Expand Assemblies to view Namespaces, expand a Namespace to view "real" Objects, and expand an Object to view its inheritance tree.
The right pane shows the object's "members". (Note: the "left" and "right" panes might display vertically if the Object Browser has a narrow space; drag its borders to spread the panes out.) When you navigate amongst the objects in the left pane, it's members will display.
Finally, the bottom pane shows the signature of whatever object or member is selected, and if available, additional textual documentation about that object or member.
List Members. This is part of .Net's IntelliSense features. It works wherever there is a dot in code. (See "Love.those.dots." below.) You can use it in either automatic or manual mode. Automatic is the factory default, but I recommend manual mode; set it to manual by going to Tools -> Options -> Text editor -> All Languages, and remove the check box next to "Auto-list members." Now, in code, either type a dot almost anywhere, or move the cursor just to the right of an existing dot, and press [ctrl]-J. If the element to the left of the dot is a valid object name, a pop-up menu of all available members will display. Select a member and press either [Enter] or dot [.] or [space], and the member will insert into your code.
Note that the list of members displayed via this feature is slightly different from the member list that displays on the Object Browser. First, the List Members will display members from not only the object to the left of the dot, but additionally any super-classes that that object has inherited. Secondly, List Members will only display overloaded members once.
Additional IntelliSense features can be found by clicking Edit -> IntelliSense.
Go to Definition. In code, right-click on any object name or member name. On the context menu, select "Go To Definition". You will be taken either to the point in code where the element was defined, or to the appropriate entry in the Object Browser. (Note: this feature works great in VB but not so great in C#. It is a mystery why this is so.)
Comments & Trackbacks
No Comments/Trackbacks for this post yet...
This post has 202 feedbacks awaiting moderation...
Leave a comment