In this chapter we discuss the style in which PowerPlant code is written, including standardized naming conventions you'll find very useful. As with all things stylistic, you are not required to follow these guidelines in your own code. However, understanding these conventions will help you understand what's happening when you are studying PowerPlant source code.

This chapter explains the following naming and coding conventions to you:

• Class and File Names
• Variable and Parameter Names
• Data Types
• Other Names
• Calling Macintosh Toolbox Routines

Class and File Names

Source files usually contain only one class. Occasionally, a file contains several classes, for example, LStdControl.cp.

Class names and file names begin with a capital letter with embedded uppercase letters for word breaks. The first letters of the class name or file name are a prefix, reflecting the kind of class. Table 3.1 lists the naming conventions.

Source and class naming conventions:

Prefix	Meaning	Example
L	PowerPlant library class	LControl
U	PowerPlant utility class	UKeyFilters
St	a stack-based class	StHandleLocker

PowerPlant uses stack-based classes to save and restore state information. Their constructors have the side effect of saving state information, and their destructors restore it. See the StHandleLocker class in UMemoryMgr.cp for an example.

Variable and Parameter Names

Variable and parameter names begin with a lowercase letter and use embedded uppercase letters for word breaks. The first letters of the variable name are a prefix, reflecting how the variable is used. Table 3.2 lists the naming conventions.

Variable and parameter naming conventions:

Prefix	Meaning	Example
m	data member of a class	mFrameSize
s	static data member	sClickCount
in	input parameter	inCommand
out	output parameter	outMenuH
io	input/output parameter	ioParam
the	a local variable	thePane

Pointers and handles are identified by a single-letter suffix. Table 3.3 lists the naming conventions.

Pointer and handle naming conventions:

Suffix	Meaning	Example
P	a pointer	theStringP
H	a handle	theMenuH

Data Types

PowerPlant declares several data types for its own use based on standard C data types.

Integer types

The type names describe the number of bits in each type. PowerPlant uses these types.

PowerPlant integer types:

Name	C type
SInt8	signed char
SInt16	signed short
SInt32	signed long
UInt8	unsigned char
UInt16	unsigned short
UInt32	unsigned long
Uchar	unsigned char
Char16	UInt16
ConstStringPtr	const unsigned char

Synonyms for integer types

Type definitions that are synonyms for other integer types end with a capital T. Table 3.5 lists the most common such types.

Other integer types:

Name	Type
CommandT	SInt32
MessageT	SInt32
ResIDT	SInt16
PaneIDT	SInt32
ClassIDT	FourCharCode
DataIDT	FourCharCode
ObjectIDT	FourCharCode

Enumerated types

Enumerated types begin with a capital E. All constants in an enumeration begin with the same prefix that identifies the type. The prefix is separated from the rest of the constant name by an underscore. For example:

enum EProgramState {
	programState_StartingUp,
	programState_ProcessingEvents,
	programState_Quitting

};

Constants

Constants always contain an underscore, used as a word break. The underscore is never the first or last character. Embedded capitals are used for other word breaks. Usually the word or words before the underscore indicate a category or kind of constant. This is similar to the naming of enumeration constants. For example:

const ResIDT resID_Default = -1;
const ResIDT resID_Undefined = -2;
const ResIDT cursor_Arrow = -1;

Resource IDs

Constants used as resource ID numbers begin with the four-character resource type code. If the resource uses illegal characters, use an approximation for those characters. For example:

const ResIDT MENU_Apple = 128;
const ResIDT ALRT_About = 128;
const ResIDT STRx_Names = 128;

Structures

Structure names begin with a capital S. PowerPlant never uses the struct keyword to define a class. In PowerPlant, a struct contains only data members and never contains member functions. For example, this is the structure that LDialogBox uses to respond to clicks in dialog buttons:

struct SDialogResponse {
	LDialogBox *dialogBox;
	void *messageParam;
};

Other Names

Preprocessor macro function names end with an underscore (_), such as Assert_() and ThrowIf_().

"Mac" embedded in a name means that the item is related to a Macintosh Toolbox data structure. "Count" embedded in a name designates a quantity, such as the number of items in a container.

The terms "Image," "Port," and "Local" used as suffixes in member function declarations relate to the coordinate system that the function uses. We'll discuss the various coordinate systems in Chapter 7, "Views."

Calling Macintosh Toolbox Routines

The PowerPlant application framework builds on the Macintosh Toolbox, it does not replace the Toolbox. Most of your programs-like PowerPlant itself-will use Macintosh Toolbox routines.

To avoid any possible name collision between a Toolbox routine and a member function of a PowerPlant class, you should always use the unary scope resolution operator (::) when you call Macintosh Toolbox routines. The PowerPlant code follows this convention almost all the time.

This practice makes it easy to distinguish Toolbox routines from member functions. Here's a code snippet from LWindow::DoSetZoom().

SetWindowStandardState(mMacWindowP, &zoomBounds);
FocusDraw();
::EraseRect(&mMacWindowP->portRect);
::ZoomWindow(mMacWindowP, inZoomOut, false);
ResizeFrameTo(zoomWidth, zoomHeight, false);

The calls to EraseRect() and ZoomWindow() are Macintosh Toolbox calls. The other calls are to member functions of the LWindow class.

Notice that PowerPlant code does not use the this-> specifier for the current object.

Summary

File, class, variable, parameter, and data type naming conventions make PowerPlant code consistent in style. This helps you understand the code more easily. Macintosh Toolbox functions are almost always called using the unary scope resolution operator. In most cases PowerPlant code does not use the this-> specifier for the current object.

You have absorbed a lot of information in this chapter. You'll find it very useful when you start exploring PowerPlant code a little later. In the next two chapters we'll explore the power and patterns you find in application frameworks in general, and in PowerPlant in particular. You're going to master the high-level design patterns used in the PowerPlant architecture.