Inside Macintosh: Overview /

Chapter 1 - Introduction

Conventions for Sample Code

The sample code presented throughout this book follows a number of conventions to help you understand the code and to distinguish application-defined routines from system software routines. For the most part, the sample code listings presented throughout the Inside Macintosh suite of books follow these conventions as well.

• Constants defined by the Venn Diagrammer application begin with the letter k. For example, the number of tools in a Venn diagram window is specified by the constant kNumTools. There are, however, several exceptions to this rule:
  • Constants specifying resource IDs begin with the letter r. For example, the resource ID of the menu bar is specified by the constant rMenuBar.
  • Constants specifying menu resource IDs begin with the letter m. For example, the resource ID of the File menu is specified by the constant mFile.
  • Constants specifying menu commands begin with the letter i. For example, the number of the Quit command in the File menu is specified by the constant iQuit.
  • Constants specifying messages displayed to the user in a window's status area begin with the letter e. For example, the message "The argument is valid." is specified by the constant eArgIsValid.

• Application global variables have names beginning with the letter g. For example, the global variable that indicates whether the user wants to quit the application is called gDone. There are no exceptions to this rule.
• Application-defined routines have names beginning with either the prefix Do or the prefix My. For example, the routine that handles window updating is called DoUpdate. Similarly, the routine that returns a random number is called MyRandom. There is one exception to this rule:
  • Application-defined routines that return Boolean values have names beginning with the prefix Is. For example, the routine that determines whether a window is a dialog box is called IsDialogWindow. Several system software routines have similar-sounding names. (For instance, the Dialog Manager provides the IsDialogEvent routine.)

• Application-defined data structures and types have names beginning with the prefix My. For example, the structure that holds information about a document window is called MyDocRec. A pointer to a record of type MyDocRec is of type MyDocRecPtr.
• Routine parameters and local variables have names beginning with the prefix my. For example, many of the routines in the Venn Diagrammer application require a window pointer as one of the parameters; this parameter is usually called myWindow. This convention has, however, many exceptions.

IMPORTANT

These naming conventions are adopted in this book (and elsewhere in Inside Macintosh) solely for reasons of consistency and clarity. They might not be suitable for your purposes.

It's worth mentioning in advance that Venn Diagrammer takes a minimalist approach to error-handling: it tries to detect any errors that might adversely affect its further processing and to work around those errors in such a way as to avoid those adverse effects. In fact, this strategy is far too simple for most applications. Your application should provide far more extensive error detection and reporting to the user. See "Handling Errors" beginning on page 176 for some further discussion of error-handling techniques.