hts reserved.
//////////////////////////////////////////////////////////////////////////////

注释程序十个很好的习惯，实际上这也是程序可维护性的关键。作为一个专业的程序员，如果写了大量的代码但是没有注释，那么这个程序员的水平就不会再提高并且会变得筋疲力尽。水平不能提高是因为没人能看懂他的程序而不能提出程序的缺陷；变得筋疲力尽是因为剩下的时间他不得不都用在这段烦人的程序上。记住，要注释程序，不要搞成这样。

有时我觉得很幸运，因为在我刚学编程时主要用的是汇编语言。如果不注释程序的话，就不得不花大量的时间来搞清在几周前到底写了些什么东西。使用C也是这样，只是程度有所不同。如果和其它12个人一起编制一个几十万行的代码，就十分有必要将当时是怎么想的以注释的形式写到程序里面。

过去我常常想不起在注释中写些什么内容，现在我基本有了一个大体的格式。例如：在每个模块的开头我都会写如上所示的注释内容，有些人喜欢将版本号也写到里面。把将版本号写到源程序控制系统（source control system）中是必要的，不然，我认为写入版本号没有什么用处。

注意:

什么是源程序控制系统（source control system）呢？这是一个用来存储和返回程序不同的版本号的工具。当发现一个大的bug时，就可以将能正常运行的程序和崩溃的程序相对照，看到底做了哪些改变。你还可以将代码分为不同的版本作不同的用途。如果你和其它的程序员共同编制一个大的程序，那么源程序控制系统将保证你和他们对程序的修改保持同步而防止了程序不统一。总起来说，对于专业程序员来说，源程序控制系统是个很重要的工具。

//////////////
// Includes //
//////////////

#include "app.h" // The definitions for this application

你或许会问：Pilot.h跑到哪里去了？头文件app.h是我们将要自定义的文件，其中将包括我们程序中所用到的所有函数的定义，在这里面是以Pilot.h为头文件的。从某种意义来讲，这是一个自定义的Pilot.h，里面增添了我们自己需要的内容。我想甚至对很大的程序来讲，这也是一个很好的方法。如果你的头文件很大，由此造成了在编译时要花费大量的时间，那么就可以先让CodeWarrior 预编译这个文件，这样会使编译速度大大加快。

///////////////////////
// Global Prototypes //
///////////////////////

DWord PilotMain( Word, Ptr, Word ); // Main entry point.
Boolean processEvent( Long ); // Processes the next event.

这些是这个模块中的函数定义的原型。我们一直在使用函数原型，但是它到底有什么作用和好处呢？函数原型可以增强函数的可维护性。当定义了函数原型后，就可以保证不会将不匹配的参数传递到函数中。如果发生此类错误的话，将会造成一些很难理解的错误，并且也不容易找到这些错误。不过，在C中是允许不使用函数原型而调用函数的。为保证这些函数的正确使用，我们将在头文件app.h中定义另一个版本。本模块头部的函数原型定义就可以保证参数的匹配和定义。

/////////////////////
// Local Variables //
/////////////////////

// The event handler list
EVENT_HANDLER_LIST

在这里定义了局部变量。这个变量乍看起来像是个语法错误。它定义在app.h中。在后面我们将详细的讲解这个变量。它定义了程序中窗体的事件处理函数。实际上，这个#define语句定义了一个函数，我们还可以用很多其它的普通的方法来定义这个事件处理函数。我想在这里应该用大写字母或其它醒目的格式来代表它，这样可以让别人（还有自己在一段时间后看代码时）能更清楚的看出这个头文件中的定义，以便弄懂它到底有什么作用。

//////////////////////
// Global Functions //
//////////////////////

//----------------------------------------------------------------------------
DWord PilotMain(
//----------------------------------------------------------------------------
// The main entry point for this application.
// Always returns zero.
//----------------------------------------------------------------------------
Word wCmd, // The launch code
Ptr, // The launch parameter block
Word ) // The launch flags
//----------------------------------------------------------------------------
{

这是我经常使用的注释形式之一。我觉得这样做很是不错，因为它很清晰，很容易在一个很长的函数模块中找到这个函数的头部。首先写出了函数的内容以及其返回值，后面注释了各个变量和参数的含义。有些人还喜欢将版本号加入到里面，但是我不想这样做，因为这样做并没有什么实际意义。

DWord dROMVersion;

// Get the ROM version
dROMVersion = 0;
FtrGet( sysFtrCreator, sysFtrNumROMVersion, &dROMVersion );

// Alert and bail if the ROM version is too low
if( dROMVersion < ROM_VERSION_MIN )
{
FrmAlert( LowROMVersionErrorAlert );

// Palm OS 1.0 will continuously re-launch this app unless we switch
// to another safe one
if( dROMVersion < ROM_VERSION_2 )
{
AppLaunchWithCommand( sysFileCDefaultApp,
sysAppLaunchCmdNormalLaunch, NULL );
}
return( 0 );
}

在以前也看到过这几行代码，它的作用就是可以防止用户的代码在不支持所用函数定义的Palm设备上运行。在我们的caculator例子中，由于使用的浮点库（floating-point libraries）只存在于Palm OS 2.0以及更高的版本，所以我们将常量ROM_VERSION_MIN定义为ROM_VERSION_2。这样只要我们使用不同的app.h就可以使main.c工作在不同的平台上，将各个模块连接在一起的“枢纽”就写在app.h里面。

// If this is not a normal launch, don't launch
if( wCmd != sysAppLaunchCmdNormalLaunch )
return( 0 );

// Initialize all parts of the application
appInit();

上面的这些代码看起来也很熟悉吧。首先确定是正常运行后，调用函数appInit（）初始化程序，它要把应用程序中所有待运行的数据初始化。例如：在Contacts程序中，我们使用appInit（）将数据库打开，在下面的具体定义中还有详细的论述。

// Go to the starting form
FrmGoto