2.6. Abstracting

In creating a description of a use case or a model of a possible class, avoid using primitive data types. Pretend that int s or double s do not exist. Almost every type of number can be described with an abstract data type (ADT). Items are priced in Dollars (or CurrencyUnit s, if you are globally oriented). The number of physical copies of an item in an inventory is a Count . The discount that a good customer receives is denoted with a Percentage . The size of a CDDisc is expressed as a Length (or LengthInMeters or LengthInInches if you are going to be sending a satellite into space). The time for a single song on a CDRelease could be stored in a TimePeriod .

Using an ADT places the focus on what can be done with the type, not on how the type is represented. An ADT shows what you intend to do with the variable. You can declare the variable as a primitive data type and name the variable to reflect that intent. However, a variable declared as an abstract data type can have built-in validation, whereas a variable declared as a primitive cannot.

Each ADT needs a related description. For example, a Count represents a number of items. A Count can be zero or positive. If a Count is negative, it represents an invalid count. Declaring a variable as a Count conveys this information. You can create variations of Count . You may have a CountWithLimit data type with a maximum count that, if exceeded, would signal an error.

You can place limits on many different data types. For example, Age s (of humans ) can range between 0 and 150 years , SpeedLimit s (for automobiles) between 5 and 80 mph, and Elevation s (for normal flying) between 0 and 60,000 feet. ^[*] All these types can be represented by an int or a double , but that is an implementation issue, not an abstraction issue.

^[*] Once upon a time, Montana had no speed limit other than "reasonable speed." The upper limit still could be a reasonable number (e.g., 200).

Abstract types can contain more than just validation. A price can be represented in Dollar s. The string representation of a Dollar differs from the string representation of a double . A string for Dollar has at least a currency symbol and perhaps some thousands separators (e.g., commas). Multiplying a Dollar by a number can result in a Dollar with cents , but not fractions of a cent. Here is a possible Dollar class:

 class Dollar         {         Dollar multiply_with_rounding(double multiplier);         Dollar add(Dollar another_dollar);         Dollar subtract(Dollar another_dollar);         String to_string(  );  //         }; 

If your language provides the ability to define operators for a class (such as + and -), you can use arithmetic symbols for the corresponding operations. You can also use the appropriate method name to have a Dollar be converted automatically to a String if it appears in an appropriate context. How you represent the abstract data type that you use for a value is an implementation detail. You can make up a class for each type. If you work with C++, you can make up typedef s for each simple type for which there is no additional functionality. For other languages, you can convert some simple types into primitive types. In that case, you might want to use variable names that include the type (e.g., double price_in_dollars ).

WHEN YOU'RE ABSTRACT, BE ABSTRACT ALL THE WAY

Do not describe data items using primitive data types.

This guideline suggests using explicit typing in describing the problem and the solution. By using abstract data types in the beginning, you are, in effect, more abstract. If you explicitly type all your attributes and parameters, you can always switch to implicit typing if the explicit typing gets in the way. It is much harder to go in reverse. ^{[ ]}

^{[ ]} For an article on strong testing with languages that have implicit typing, see http://www.artima.com/weblogs/viewpost.jsp?thread=4639.

ADTS AND SPEED OF DEVELOPMENT

I was the chief judge of the Droege Developer Competition. In this event, pairs of developers competed to code a project for a nonprofit organization in one day. They were provided specifications and the results were judged the next day. Developers who used a product from Magic Software (http://www.magicsoftware.com/) consistently scored high and often won the competition. That product includes the ability to define data types that contain validation rules, display rules (e.g., drop-down lists or radio buttons ), and formatting rules. The record layout in the tables is defined using these data types, rather than primitive Structured Query Language (SQL) types. To display a record, the record fields were placed onto the display window. The requisite formatting and validation for each field were already coded. Additional validation could be added when necessary.

The data typing feature, which is a particular implementation of abstract data typing, was key in the ability to create a working system quickly.

2.6.1. Not Just a String

A more descriptive data type can represent many data types represented typically by a String . For example, although a name can be declared as a String , you could declare it as a clumped data object:

 class Name         {         String first_name;         String last_name;         String title;          // e.g. Mr. Mrs.         String suffix;      // e.g. Jr. III         }; 

To avoid the "everything is a String " syndrome, come up with a different type name to describe a variable that holds a set of characters that does not have any validation, formatting, or other meta-information associated with it. Suppose you decide on CommonString . Use that name in place of String to declare the data types of attributes, and reserve String as an implementation type. Then ask the question "Is that attribute really a CommonString ?"

Let us revisit the Address class. Using CommonString , we can describe the class as follows :

 class Address         {         CommonString line1;         CommonString line2;         CommonString city;         CommonString state;         CommonString zipcode;         } 

CommonString s can contain any characters, just like an int can contain any integer values (within hardware limits). In Address , some fields are definitely not CommonString s. A state is not a CommonString . Only certain values represent a valid state. For U.S. postal addresses, if we use abbreviations to represent the state, the abbreviation must appear on the U.S. Postal Service's official list of abbreviations. So the state should be declared as a data type called State . This data type can provide an appropriate validation mechanism. That mechanism can check to see that a string is in the official list, or it can supply a set of strings of all official abbreviations for use in a drop-down display box.

A U.S. Zip Code is not just a CommonString either. You can describe it as a NumericString data type (e.g., one with all digits), as a FormattedString data type (one with five digits plus a dash plus four digits), or as a ZipCode data type. If any combination of digits was valid, using NumericString or FormattedString might be appropriate. However, declaring the attribute as a ZipCode type allows us to abstract away its actual representation.

Do not combine classes simply for implementation purposes. You can define both SocialSecurityNumber s and PhoneNumber s as strings of digits with two dashes. That does not make them equivalent ”that is just accidental cohesion. They are two distinctly different classes with different validation. A phone number in the U.S. cannot begin with a 1 or a 0. Certain ranges of Social Security numbers are not used. These numbers can use the same type of formatted string for input or display purposes, but the semantics of each class are entirely different. You would never send a Social Security number to be dialed , nor would you attempt to record payroll taxes against a phone number. (All right, someone at some time will come up with a counterexample, so perhaps I should never say "never.")

Much data that might be a CommonString can be assigned its own data type. For example, filenames are usually typed as strings, but they cannot contain certain characters. In the Windows world, you cannot have any of the following characters in a filename: \ , / , : , * , " , ? , < , > , or . A FileName data type can represent a filename and enforce this limitation. An advantage of using a data type becomes apparent in graphical user interface (GUI) development. For instance, the user interface code could recognize the FileName data type and automatically insert a browse button next to a text field.

On the Web, parameter values for the Hypertext Transfer Protocol (HTTP) commands GET and PUT use encoded strings. Characters that are not alphabetic or numeric are encoded using their hexadecimal values. The encoded string is sent to the web server. Although the unencoded string and the encoded string are both implemented with strings, they are different. You can have invalid encoded strings ”ones with unencoded punctuation, such as a hacker might send to a server. You could use an EncodedWebString class to represent strings on a server. If an input were not validated as an EncodedWebString , it would be rejected.

MOST STRINGS ARE MORE THAN JUST A STRING

Treat String as a primitive data type. Describe attributes with abstract data types, instead of as String s.

2.6.2. Constant Avoidance

Similar to the way in which most strings are more than strings, most constant values are more than just constants. A constant value can usually be assigned a name that denotes the meaning of that constant. Avoid using the explicit value in a specification or executable code. ^[*] Declare the value as a constant and use the name of that constant in the document or the code.

^[*] Michael Green, a reviewer, called this principle "No magic numbers!" after having to deal with numbers that could not be changed or removed (without negative side effects in apparently unrelated code). He could find no one who knew what they were for or why they were there.

If Sam mentions that the late fee for a rental is $3, I create a constant:

 Dollar RENTAL_LATE_FEE = 3.00; 

When reading the relevant documents later on, I need not concentrate on the actual value, only on the assigned name. Suppose this value was not transformed into a constant and the value of 3.00 was used frequently in the documents for other purposes. If I went searching for it, I would have to examine each appearance carefully to see if it was a reference to the rental late fee or to some other value.

You might not get rid of every constant value. The value often appears in initializing variables or setting the initial index for an array. There is little to be gained by creating a named constant for zero.

If the value that a name represents is subject to change, the value should be kept with a configuration mechanism. In that case, the code would use the symbolic name to look up the configured value. The configuration mechanism could use an XML configuration file, a database table, or another form of persistence to store the values. For example, RENTAL_LATE_FEE is probably something that should exist in a configuration file rather than a constant.

NEVER LET A CONSTANT SLIP INTO CODE

Use a symbolic name for all values.

DON'T THROW AWAY INFORMATION

When I was presenting these prefactoring guidelines in a talk at the Software Development Conference, Jerry Weinberg made an interesting observation about some of the guidelines in this chapter. He stated that they revolve around the central principle of not throwing away information. For example, describing a price as a double , rather than as a Dollar , decreases the information about the price. Lumping a group of concepts into a single class, rather than splitting them into multiple classes, hides information. Now, if I only could have convinced my mother that my comic book collection was really information...