Wind River 的编码习惯.doc

Wind River的编码习惯 1.1 介绍 本文档详细说明了Wind River的C代码和包含在代码中的附加文档的编写习惯。 这些习惯是特意约定的，不全，但是能写出更高质量的代码。每一个源模块必须包含某些基本的文档，并且这些代码和文档必须具备一个好的格式以便于阅读和理解。 这些习惯也用来在不同的程序员之间提供一个统一的编码标准，这样就能减少在别人的代码上工作时因为不同的代码风格所做的额外调整。同时，也能允许对代码的自动处理。比如，可以写一些程序来自动生成参考手册，模块摘要，更新说明等。 本文档所描述的编码习惯由以下两部分组成： 文件标题：无论什么编程语言，在每一个源文件的头部都有一个统一的标题说明 C代码习惯 1.2 文件标题 每一个包含C代码的文件，不管它是头文件，资源文件，或者是一个使用主机工具、库例程或应用程序的文件，都必须包含一个标准的文件标题。 文件标题由下面描述的几块组成，这些块由一个或几个空行分开，但是在每一个块里面不能有空行，以便于文件标题的自动处理。 名称：由一行注释组成，包含工具，库或应用程序的名字，以及一个简短的描述。名字必须跟文件名一样。这一行将变成自动处理后的参考条目和索引中的名称。 版权：由一行注释组成，包含适当的版权信息。 更改历史：包含一个注释块，就是C语言中的多行注释。更改历史中的每一个条目包含版本号、更改时间、更改人和有关更改内容的完整描述。 版本号由两个阿拉伯数字和一个字符组成（例如，03C）。字符的增加表示一个内部的改动（小的改动），数字的增加表示一个大的改动，特别是改变了模块的外部接口。 下面是一个标准的C源文件的文件标题的例子： Example I-1:??Standard File Heading (C Version) /* fooLib.c - foo subroutine library */ /* Copyright 1984-1995 Wind River Systems, Inc. */ /* modification history -------------------- 02a,15sep92,nfs??added defines MAX_FOOS and MIN_FATS. 01b,15feb86,dnw??added routines fooGet() and fooPut(); ?????????????????added check for invalid index in?fooFind(). 01a,10feb86,dnw??written. */ 1.3 C代码习惯 分成下面几个种类 模块布局 子程序布局 代码布局 命名习惯 风格 头文件布局 文档生成 1.3.1 C模块布局 一个模块是指在一个单一文件中的所有代码单元。模块标题紧跟在文件标题之后，由以下几块组成，每一块之间由一个或几个空行隔开。 在更新历史之后和第一个函数或可执行的模块代码之前，如果需要，必须按照顺序包含下面的几个部分： 模块文档概要：由注释块组成，包含所有模块目的和功能的一个完整的描述，特别是外部接口。包括相关的包含头文件。格式为INCLUDE FILES:文件列表。 包含头文件：由一个包含includes字样的单行注释加上一行或多行C的预处理宏#include组成。 这部分包含了本模块需要包含的所有头文件。 定义：由一个包含defines字样的单行注释加上一个或多个C的预处理宏#define组成。这部分包含了本模块所需要的所有定义。 类型：由一个包含typedefs字样的单行注释加上一个或多个C的typedef声明组成。这部分包含了本模块需要的所有类型定义。 全局变量：由一个包含globals字样的单行注释加上一个或多个C的全局定义组成，每行一个。这部分包含了所有希望在本模块外能访问的变量的定义。 本地变量：由一个包含local字样的单行注释加上一个或多个C的局部定义组成，每行一个。这部分包含了所有不希望在本模块外能访问的变量的定义。 前向声明：由一个包含forward declarations字样的单行注释加上一个或多个ANSI C的函数原型声明组成，每行一个。这部分包含了所有本模块中定义的函数原型。前向声明仅仅用于本地函数，其它类型的函数在头文件中声明。 下面是一个例子，包含文件标题： Example I-2:??C File and Module Headings /* fooLib.c - foo subroutine library */ /* Copyright 1984-1995 Wind River Systems, Inc. */ /* modificat