MacApp Coding Style

MacApp


	Log In \| Not a Member?	Contact ADC

Audience

An engineer writing code for inclusion in the MacApp framework.

Over the years a certain MacApp coding style has emerged. This style is maintained throughout the source code of MacApp in order to present a consistent and comfortable presentation to our developers. They gain a feeling of 'security' from this consistency.

Here we present a list of the standard MacApp coding styles. This list will grow and change as time permits.

Why Styles?

Automated scripts are used for generating a public release of MacApp & ACS. Following these standards prevents script-busting problems from occuring.

Styles

Here we present a list of the standard MacApp coding styles. This list will grow and change as time permits.

Change History

Include a change history. Insure that the change history uses the standard format appropriate for the type of file. For example, a C or C++ source code file should have the following form at the beginning of the source file:

//------------------------ ... ------------------------
// UFileBasedDocument.cp
// Copyright © 1984-1997 by Apple Computer, Inc. All rights reserved.
//------------------------ ... ------------------------

/*
Change History:
06/31/96 hyr [1402919] Changed nil back to NULL.
----- R11 -----
06/27/96 srg Make conditional tests...
06/15/96 hyr [1390076] Don't create existingFileCopy...
*/

There are several things to notice about this example which are important to follow when checking in your code. The placement of each item in the Change History and the use of tabs for separation are critical for the successful running of severel release preparation scipts which rely on the standard layout.

The title 'Change History:' is preceeded with one tab (no spaces) and has no trailing whitespace or additional comments (the colon is the last character on the line).

The date for each change notice is preceeded by two tabs and followed by one tab. The initials of the person making the change are followed by two tabs.

Change comments can span multiple lines. The second and subsequent lines should be indented to align with the beginning of the comment on the first line. For ease in scanning the change history it is considered 'polite' to keep each line short enough to be fully readable when the window is sized reasonably.

The Radar bug number is normally included at the beginning of a change comment.

Braces

Always place beginning braces on their own line and align with the statement which begins the block.

if (myFoo->IsGoodTasting())
{
// Your good tasting code goes here.
}

Naming - Data Members

Class data members always start with the small letter 'f'.

class TFoo
{
...
private:
short fHappyFactor;
}

Naming - Static Data Members

Static class data members always start with the small letters 'sf'.

class TFoo
{
private:
static short sfHappinessCount;
}

Naming - Global Variables

Global variables always start with the small letters 'g'.

short gAreWeHappy;

But the use of globals is discouraged.

Const

Always declare functions 'const' if at all possible.

virtual short GetMyValue() const;

Unused Parameters

Always include a parameter name in a function definition and implementation. Never comment out the parameter name in the definition or the implementation. Instead of commenting out unused parameters in the implementation use #pragma unused (...).

The following examples show proper formatting of parameter names:

short DoFoo(short myUnusedArg);   // Definition

short DoFoo(short myUnusedArg)    // Implementation

   {

      #pragma unused (myUnusedArg)

      ...

   }

The following examples show improper formatting of parameter names:

short DoFoo(short /* myUnusedArg */);  // Don't comment in definition.

short DoFoo(short)                     // Don't omit name.

   {

      ...

   }

short DoFoo(short /*myUnusedArg*/)     // Don't comment in implementation.>

   {

      ...

   }

Using the recommended format for the commenting out of unused arguments simplifies the automatic generation of documentation.

Action-Required Annotation

On occasion an engineer will want to place an annotation in the source code indicating something that will require follow-up some indeterminite time in the future. Very often it is also desirable to include the engineer's initials in these annotations.

The following is the recommended format for annotation comments:

// ••• [gru] The following section is inefficient.  Rework!

   TView*  aView = myView;  // ••• Should use autoptr here!

Use of the recommended format will make the preparation of a formal release much easier since a part of that process is the scanning for and stripping of personal identification information.

You may also indicate an action item using #pragma message ("..."). The following is an example:

#pragma message ("TView::GetView:  The following section is inefficient.  Rework!")

   TView*  aView = myView;  // ••• Should use autoptr here!

Note that the message includes the name of the function containing the comment. Including the function name aids in locating the code in question during a build.

In this case it is not necessary to also include the '//' comment.

Copyright Notice

Every source file should include a copyright notice. This copyright notice can take one of four forms depending on the number of years the file has been in existence and the type of file.

For regular source code, such as C++, assembler, scripts, etc. the copyright should take one of the two following forms, commented as appropriate for the specific source file:

  ...  Copyright © 1999 by Apple Computer, Inc.  All rights reserved.



  ...  Copyright © 1994-1999 by Apple Computer, Inc.  All rights reserved.

For html, such as used in web pages, the copyright should take one of the two following forms:

  ...  Copyright &copy; 1999 by Apple Computer, Inc.  All rights reserved.



  ...  Copyright &copy; 1994-1999 by Apple Computer, Inc.  All rights reserved.

Use of the recommended format will facilitate the running of automated scripts which update the copyright year.