In the following example, an application uses event objects to prevent several threads from reading from a shared memory buffer while a master thread is writing to that buffer. First, the master thread uses the CreateEvent function to create a manual-reset event object. The master thread sets the event object to nonsignaled when it is writing to the buffer and then resets the object to signaled when it has finished writing. Then it creates several reader threads and an auto-reset event object for each thread. Each reader thread sets its event object to signaled when it is not reading from the buffer.

#define NUMTHREADS 4
HANDLE hGlobalWriteEvent;
void CreateEventsAndThreads(void)
{
HANDLE hReadEvents[NUMTHREADS], hThread;
DWORD i, IDThread;
// Create a manual-reset event object. The master thread sets
// this to nonsignaled when it writes to the shared buffer.
hGlobalWriteEvent = CreateEvent(
NULL,         // no security attributes
TRUE,         // manual-reset event
TRUE,         // initial state is signaled
"WriteEvent"  // object name
);
if (hGlobalWriteEvent == NULL) {
// error exit
}
// Create multiple threads and an auto-reset event object
// for each thread. Each thread sets its event object to
// signaled when it is not reading from the shared buffer.
for(i = 1; i <= NUMTHREADS; i++)
{
// Create the auto-reset event.
hReadEvents[i] = CreateEvent(
NULL,     // no security attributes
FALSE,    // auto-reset event
TRUE,     // initial state is signaled
NULL);    // object not named
if (hReadEvents[i] == NULL)
{
// Error exit.
}
hThread = CreateThread(NULL, 0,
(LPTHREAD_START_ROUTINE) ThreadFunction,
&hReadEvents[i],  // pass event handle
0, &IDThread);
if (hThread == NULL)
{
// Error exit.
}
}
}

Before the master thread writes to the shared buffer, it uses the ResetEvent function to set the state of hGlobalWriteEvent (an application-defined global variable) to nonsignaled. This blocks the reader threads from starting a read operation. The master then uses the WaitForMultipleObjects function to wait for all reader threads to finish any current read operations. When WaitForMultipleObjects returns, the master thread can safely write to the buffer. After it has finished, it sets hGlobalWriteEvent and all the reader-thread events to signaled, enabling the reader threads to resume their read operations.

VOID WriteToBuffer(VOID)
{
DWORD dwWaitResult, i;
// Reset hGlobalWriteEvent to nonsignaled, to block readers.
if (! ResetEvent(hGlobalWriteEvent) )
{
// Error exit.
}
// Wait for all reading threads to finish reading.
dwWaitResult = WaitForMultipleObjects(
NUMTHREADS,   // number of handles in array
hReadEvents,  // array of read-event handles
TRUE,         // wait until all are signaled
INFINITE);    // indefinite wait
switch (dwWaitResult)
{
// All read-event objects were signaled.
case WAIT_OBJECT_0:
// Write to the shared buffer.
break;
// An error occurred.
default:
printf("Wait error: %d\n", GetLastError());
ExitProcess(0);
}
// Set hGlobalWriteEvent to signaled.
if (! SetEvent(hGlobalWriteEvent) )
{
// Error exit.
}
// Set all read events to signaled.
for(i = 1; i <= NUMTHREADS; i++)
if (! SetEvent(hReadEvents[i]) ) {
// Error exit.
}
}

Before starting a read operation, each reader thread uses WaitForMultipleObjects to wait for the application-defined global variable hGlobalWriteEvent and its own read event to be signaled. When WaitForMultipleObjects returns, the reader thread's auto-reset event has been reset to nonsignaled. This blocks the master thread from writing to the buffer until the reader thread uses the SetEvent function to set the event's state back to signaled.

VOID ThreadFunction(LPVOID lpParam)
{
DWORD dwWaitResult;
HANDLE hEvents[2];
hEvents[0] = *(HANDLE*)lpParam;  // thread's read event
hEvents[1] = hGlobalWriteEvent;
dwWaitResult = WaitForMultipleObjects(
2,            // number of handles in array
hEvents,      // array of event handles
TRUE,         // wait till all are signaled
INFINITE);    // indefinite wait
switch (dwWaitResult)
{
// Both event objects were signaled.
case WAIT_OBJECT_0:
// Read from the shared buffer.
break;
// An error occurred.
default:
printf("Wait error: %d\n", GetLastError());
ExitThread(0);
}
// Set the read event to signaled.
if (! SetEvent(hEvents[0]) )
{
// Error exit.
}
}

You can use a mutex object to protect a shared resource from simultaneous access by multiple threads or processes. Each thread must wait for ownership of the mutex before it can execute the code that accesses the shared resource. For example, if several threads share access to a database, the threads can use a mutex object to permit only one thread at a time to write to the database.

In the following example, a process uses the CreateMutex function to create a named mutex object or open a handle to an existing mutex object.

HANDLE hMutex;
// Create a mutex with no initial owner.
hMutex = CreateMutex(
NULL,                       // no security attributes
FALSE,                      // initially not owned
"MutexToProtectDatabase");  // name of mutex
if (hMutex == NULL)
{
// Check for error.
}

When a thread of this process writes to the database, as in the next example, it first requests ownership of the mutex. If it gets ownership, the thread writes to the database and then releases its ownership.

The example uses structured exception-handling syntax to ensure that the thread properly releases the mutex object. The __finally block of code is executed no matter how the __try block terminates (unless the __try block includes a call to the TerminateThread function). This prevents the mutex object from being abandoned inadvertently.

BOOL FunctionToWriteToDatabase(HANDLE hMutex)
{
DWORD dwWaitResult;
// Request ownership of mutex.
dwWaitResult = WaitForSingleObject(
hMutex,   // handle to mutex
5000L);   // five-second time-out interval
switch (dwWaitResult)
{
// The thread got mutex ownership.
case WAIT_OBJECT_0:
__try {
// Write to the database.
}
__finally {
// Release ownership of the mutex object.
if (! ReleaseMutex(hMutex)) {
// Deal with error.
}
break;
}
// Cannot get mutex ownership due to time-out.
case WAIT_TIMEOUT:
return FALSE;
// Got ownership of the abandoned mutex object.
case WAIT_ABANDONED:
return FALSE;
}
return TRUE;
}

详细解说STL string

0 前言: string 的角色

举例来说，如果文本格式是：用户名 电话号码，文件名name.txt BeautifierPlugin Error: Unable to handle "bash" syntax.

Tom 23245332
Jenny 22231231
Heny 22183942
Tom 23245332
...

那么在shell 编程中，可以这样用： BeautifierPlugin Error: Unable to handle "bash" syntax.

awk '{print $1}' name.txt | sort | uniq

如果使用C/C++ 就麻烦了，他需要做以下工作：

1. 先打开文件，检测文件是否打开，如果失败，则退出。
2. 声明一个足够大得二维字符数组或者一个字符指针数组
3. 读入一行到字符空间
4. 然后分析一行的结构，找到空格，存入字符数组中。
5. 关闭文件
6. 写一个排序函数，或者使用写一个比较函数，使用qsort排序
7. 遍历数组，比较是否有相同的，如果有，则要删除，copy...
8. 输出信息

当然，有了STL，这些处理会得到很大的简化。我们可以使用 fstream来代替麻烦的fopen fread fclose, 用vector 来代替数组。最重要的是用 string来代替char * 数组，使用sort排序算法来排序，用unique 函数来去重。听起来好像很不错 。看看下面代码(例程1）：

#include <string>
#include <iostream>
#include <algorithm>
#include <vector>
#include <fstream>
using namespace std;
int main(){
ifstream in("name.txt");
string strtmp;
vector<string> vect;
while(getline(in, strtmp, '\n'))
vect.push_back(strtmp.substr(0, strtmp.find(' ')));
sort(vect.begin(), vect.end());
vector<string>::iterator it=unique(vect.begin(), vect.end());
copy(vect.begin(), it, ostream_iterator<string>(cout, "\n"));
return 0;
}

当然，在这个文本格式中，不用vector而使用map会更有扩充性，例如，还可通过人名找电话号码等等，但是使用了map就不那么好用sort了。你可以用map试一试。

这里string的作用不只是可以存储字符串，还可以提供字符串的比较，查找等。在sort和unique函数中就默认使用了less 和equal_to函数, 上面的一段代码，其实使用了string的以下功能：

1. 存储功能，在getline() 函数中
2. 查找功能，在find() 函数中
3. 子串功能，在substr() 函数中
4. string operator < , 默认在sort() 函数中调用
5. string operator == , 默认在unique() 函数中调用

总之，有了string 后，C++的字符文本处理功能总算得到了一定补充，加上配合STL其他容器使用，其在文本处理上的功能已经与perl, shell, php的距离缩小很多了。 因此掌握string 会让你的工作事半功倍。

1 string 使用

extern "C++" {
typedef basic_string <char> string;
typedef basic_string <wchar_t> wstring;
} // extern "C++"

string 其实相当于一个保存字符的序列容器，因此除了有字符串的一些常用操作以外，还有包含了所有的序列容器的操作。字符串的常用操作包括：增加、删除、修改、查找比较、链接、输入、输出等。详细函数列表参看附录。不要害怕这么多函数，其实有许多是序列容器带有的，平时不一定用的上。

如果你要想了解所有函数的详细用法，你需要查看basic_string，或者下载STL编程手册。这里通过实例介绍一些常用函数。

1.1 充分使用string 操作符

#include <string>
#include <iostream>
using namespace std;
int main(){
string strinfo="Please input your name:";
cout << strinfo ;
cin >> strinfo;
if( strinfo == "winter" )
cout << "you are winter!"<<endl;
else if( strinfo != "wende" )
cout << "you are not wende!"<<endl;
else if( strinfo < "winter")
cout << "your name should be ahead of winter"<<endl;
else
cout << "your name should be after of winter"<<endl;
strinfo += " , Welcome to China!";
cout << strinfo<<endl;
cout <<"Your name is :"<<endl;
string strtmp = "How are you? " + strinfo;
for(int i = 0 ; i < strtmp.size(); i ++)
cout<<strtmp[i];
return 0;
} 

下面是程序的输出 BeautifierPlugin Error: Unable to handle "bash" syntax.

-bash-2.05b$ make tt
c++  -O -pipe -march=pentiumpro  tt.cpp  -o tt
-bash-2.05b$ ./tt
Please input your name:Hero
you are not wende!
Hero , Welcome to China!
How are you? Hero , Welcome to China!

有了这些操作符，在STL中仿函数都可以直接使用string作为参数，例如 less, great, equal_to 等，因此在把string作为参数传递的时候，它的使用和int 或者float等已经没有什么区别了。例如，你可以使用：

map<string, int> mymap;
//以上默认使用了 less<string>

string strinfo="Winter";
string strlast="Hello " + strinfo + "!";
//你还可以这样：
string strtest="Hello " + strinfo + " Welcome" + " to China" + " !";

1. 系统遇到"+"号，发现有一项是string 对象。
2. 系统把另一项转化为一个临时 string 对象。
3. 执行 operator + 操作，返回新的临时string 对象。
4. 如果又发现"+"号，继续第一步操作。

有了操作符以后，assign(), append(), compare(), at()等函数，除非有一些特殊的需求时，一般是用不上。当然at()函数还有一个功能，那就是检查下标是否合法，如果是使用：

string str="winter";
//下面一行有可能会引起程序中断错误
str[100]='!';
//下面会抛出异常:throws: out_of_range
cout<<str.at(100)<<endl;

1.2 眼花缭乱的string find 函数

size_type find_first_of(const basic_string& s, size_type pos = 0)
size_type find_first_of(const charT* s, size_type pos, size_type n)
size_type find_first_of(const charT* s, size_type pos = 0)
size_type find_first_of(charT c, size_type pos = 0)

template <class _CharT, class _Traits, class _Alloc>
const basic_string<_CharT,_Traits,_Alloc>::size_type
basic_string<_CharT,_Traits,_Alloc>::npos
= basic_string<_CharT,_Traits,_Alloc>::size_type) -1;

find 和 rfind 都还比较容易理解，一个是正向匹配，一个是逆向匹配，后面的参数pos都是用来指定起始查找位置。对于find_first_of 和find_last_of 就不是那么好理解。

find_first_of 是给定一个要查找的字符集，找到这个字符集中任何一个字符所在字符串中第一个位置。或许看一个例子更容易明白。

有这样一个需求：过滤一行开头和结尾的所有非英文字符。看看用string 如何实现：

#include <string>
#include <iostream>
using namespace std;
int main(){
string strinfo="   //*---Hello Word!......------";
string strset="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
int first = strinfo.find_first_of(strset);
if(first == string::npos) {
cout<<"not find any characters"<<endl;
return -1;
}
int last = strinfo.find_last_of(strset);
if(last == string::npos) {
cout<<"not find any characters"<<endl;
return -1;
}
cout << strinfo.substr(first, last - first + 1)<<endl;
return 0;
}

Hello Word

张三|3456123, 湖南
李四,4564234| 湖北
王小二, 4433253|北京
...

1.3 string insert, replace, erase

string只是提供了按照位置和区间的replace函数，而不能用一个string字串来替换指定string中的另一个字串。这里写一个函数来实现这个功能：

void string_replace(string & strBig, const string & strsrc, const string &strdst) {
string::size_type pos=0;
string::size_type srclen=strsrc.size();
string::size_type dstlen=strdst.size();
while( (pos=strBig.find(strsrc, pos)) != string::npos){
strBig.replace(pos, srclen, strdst);
pos += dstlen;
}
}

#include <string>
#include <iostream>
using namespace std;
int main() {
string strinfo="This is Winter, Winter is a programmer. Do you know Winter?";
cout<<"Orign string is :\n"<<strinfo<<endl;
string_replace(strinfo, "Winter", "wende");
cout<<"After replace Winter with wende, the string is :\n"<<strinfo<<endl;
return 0;
}

Orign string is :
This is Winter, Winter is a programmer. Do you know Winter?
After replace Winter with wende, the string is :
This is wende, wende is a programmer. Do you know wende?

void string_replace(string & strBig, const string & strsrc, const string &strdst) {
string::size_type pos=0;
string::size_type srclen=strsrc.size();
string::size_type dstlen=strdst.size();
while( (pos=strBig.find(strsrc, pos)) != string::npos){
strBig.erase(pos, srclen);
strBig.insert(pos, strdst);
pos += dstlen;
}
}

2 string 和 C风格字符串

string_replace(strinfo, "Winter", "wende");

void string_replace(string & strBig, const string & strsrc, const string &strdst) 

const charT* c_str() const
const charT* data() const
size_type copy(charT* buf, size_type n, size_type pos = 0) const 

1. c_str 直接返回一个以\0结尾的字符串。
2. data 直接以数组方式返回string的内容，其大小为size()的返回值，结尾并没有\0字符。
3. copy 把string的内容拷贝到buf空间中。

const charT* c_str () const
{ if (length () == 0) return ""; terminate (); return data (); }

对于c_str() data()函数，返回的数组都是由string本身拥有，千万不可修改其内容。其原因是许多string实现的时候采用了引用机制，也就是说，有可能几个string使用同一个字符存储空间。而且你不能使用sizeof(string)来查看其大小。详细的解释和实现查看Effective STL的条款15：小心string实现的多样性。

另外在你的程序中，只在需要时才使用c_str()或者data()得到字符串，每调用一次，下次再使用就会失效，如：

string strinfo("this is Winter");
...
//最好的方式是:
foo(strinfo.c_str());
//也可以这么用:
const char* pstr=strinfo.c_str();
foo(pstr);
//不要再使用了pstr了, 下面的操作已经使pstr无效了。
strinfo += " Hello!";
foo(pstr);//错误！

3 string 和 Charactor Traits

template <class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT> >
class basic_string
{
//...
}

就像Steve Donovan在过度使用C++模板中提到的，这些确实有些过头了，要不是系统自己定义了相关的一些属性，而且用了个typedef，否则还真不知道如何使用。

但复杂总有复杂道理。有了char_traits，你可以定义自己的字符串类型。当然，有了char_traits < char > 和char_traits < wchar_t > 你的需求使用已经足够了，为了更好的理解string ，咱们来看看char_traits都有哪些要求。

如果你希望使用你自己定义的字符，你必须定义包含下列成员的结构：

表达式	描述
char_type	字符类型
int_type	int 类型
pos_type	位置类型
off_type	表示位置之间距离的类型
state_type	表示状态的类型
assign(c1,c2)	把字符c2赋值给c1
eq(c1,c2)	判断c1,c2 是否相等
lt(c1,c2)	判断c1是否小于c2
length(str)	判断str的长度
compare(s1,s2,n)	比较s1和s2的前n个字符
copy(s1,s2, n)	把s2的前n个字符拷贝到s1中
move(s1,s2, n)	把s2中的前n个字符移动到s1中
assign(s,n,c)	把s中的前n个字符赋值为c
find(s,n,c)	在s的前n个字符内查找c
eof()	返回end-of-file
to_int_type(c)	将c转换成int_type
to_char_type(i)	将i转换成char_type
not_eof(i)	判断i是否为EOF
eq_int_type(i1,i2)	判断i1和i2是否相等

想看看实际的例子，你可以看看sgi STL的char_traits结构源码.

现在默认的string版本中，并不支持忽略大小写的比较函数和查找函数，如果你想练练手，你可以试试改写一个char_traits , 然后生成一个case_string类, 也可以在string 上做继承，然后派生一个新的类，例如：ext_string，提供一些常用的功能，例如：

1. 定义分隔符。给定分隔符，把string分为几个字段。
2. 提供替换功能。例如，用winter, 替换字符串中的wende
3. 大小写处理。例如，忽略大小写比较，转换等
4. 整形转换。例如把"123"字符串转换为123数字。

4 string 建议

1. string并不是万能的，如果你在一个大工程中需要频繁处理字符串，而且有可能是多线程，那么你一定要慎重(当然，在多线程下你使用任何STL容器都要慎重)。
2. string的实现和效率并不一定是你想象的那样，如果你对大量的字符串操作，而且特别关心其效率，那么你有两个选择，首先，你可以看看你使用的STL版本中string实现的源码；另一选择是你自己写一个只提供你需要的功能的类。
3. string的c_str()函数是用来得到C语言风格的字符串，其返回的指针不能修改其空间。而且在下一次使用时重新调用获得新的指针。
4. string的data()函数返回的字符串指针不会以'\0'结束，千万不可忽视。
5. 尽量去使用操作符，这样可以让程序更加易懂（特别是那些脚本程序员也可以看懂）

5 小结

6 附录

7 参考文章

1. SGI STL: char_traits 源码
2. STL 编程手册: basic_string
3. 详细解说 STL 排序(Sort)
4. 详细解说 STL hash_map系列
5. Effective STL 中文版

0. 序言
为代码写注释一直是大多数程序员有些困扰的事情。当前程序员都能接受为了程序的可维护性、可读性编码的同时写注释的说法，但对哪些地方应该写注释，注释如何写，写多少等这些问题，很多程序员仍然没有答案。更头痛的是写文档，以及维护文档的问题，开发人员通常可以忍受编写或者改动代码时编写或者修改对应的注释，但之后需要修正相应的文档却比较困难。如果能从注释直接转化成文档，对开发人员无疑是一种福音。而doxygen就能把遵守某种格式的注释自动转化为对应的文档。

Doxygen是基于GPL的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统上运行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目（包括前两篇文章介绍的log4cpp和CppUnit）都使用了doxygen文档系统。而国内的开发人员却使用的不多，这里从开发人员使用的角度介绍这个工具，使开发人员用最少的代价尽快掌握这种技术，并结合这个工具探讨如何撰写注释的问题。以下以linux下的C++语言为例进行介绍，以下讨论基于doxygen1.3.3。

1. doxygen使用步骤
由于只是工具的使用，这里不介绍它的原理，直接从使用步骤开始。Doxygen的使用步骤非常简单。主要可以分为：
 1）第一次使用需要安装doxygen的程序
 2）生成doxygen配置文件
 3）编码时，按照某种格式编写注释
 4）生成对应文档
doxygen的安装非常简单， linux下可以直接下载安装包运行即可，下载源代码编译安装也是比较通用的编译安装命令。请参考其安装文档完成安装。

Doxygen在生成文档时可以定义项目属性以及文档生成过程中的很多选项，使用下面命令能够产生一个缺省的配置文件：
doxygen -g  [配置文件名]
可以根据项目的具体需求修改配置文件中对应的项，具体的修改过程在下面介绍。修改过的配置文件可以作为以后项目的模板。

让doxygen自动产生文档，平常的注释风格可不行，需要遵循doxygen自己的格式。具体如何写doxygen认识的注释在第3节详细介绍。

OK，代码编完了，注释也按照格式写好了，最后的文档是如何的哪？非常简单，运行下面的命令，相应的文档就会产生在指定的目录中。
  doxygen [配置文件名]

需要注意的是doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、变量、宏等注释，而忽略函数内变量、代码等的注释。

2. doxygen配置文件
doxygen配置文件的格式是也是通常的unix下配置文件的格式：注释'#'开始；tag = value [,value2…]；对于多值的情况可以使用 tag += value [,value2…]。

对doxygen的配置文件的修改分为两类：一种就是输出选项，控制如何解释源代码、如何输出；一种就是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。下面选择重要的，有可能需要修改的选项进行解释说明，其他选项在配置文件都有详细解释。

TAG 缺省值 含义
PROJECT_NAME  项目名称
PROJECT_NUMBER  可以理解为版本信息
OUTPUT_DIRECTORY  输出文件到的目录，相对目录（doxygen运行目录）或者绝对目录
INPUT  代码文件或者代码所在目录，使用空格分割
FILE_PATTERNS *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl 指定INPUT的目录中特定文件，如：*.cpp *.c *.h
RECURSIVE NO 是否递归INPUT中目录的子目录
EXCLUDE  在INPUT目录中需要忽略的子目录
EXCLUDE_PATTERNS  明确指定的在INPUT目录中需要忽略的文件，如：FromOut*.cpp
  
OUTPUT_LANGUAGE English 生成文档的语言，当前支持2、30种语言，国内用户可以设置为Chinese
USE_WINDOWS_ENCODING YES（win版本）
NO（unix版本） 编码格式，默认即可。
EXTRACT_ALL NO 为NO，只解释有doxygen格式注释的代码；为YES，解析所有代码，即使没有注释。类的私有成员和所有的静态项由EXTRACT_PRIVATE和 EXTRACT_STATIC控制
EXTRACT_PRIVATE NO 是否解析类的私有成员
EXTRACT_STATIC NO 是否解析静态项
EXTRACT_LOCAL_CLASSES YES 是否解析源文件（cpp文件）中定义的类
SOURCE_BROWSER NO 如果为YES，源代码文件会被包含在文档中
INLINE_SOURCES NO 如果为YES，函数和类的实现代码被包含在文档中
ALPHABETICAL_INDEX NO 生成一个字母序的列表，有很多类、结构等项时建议设为YES
GENERATE_HTML YES 是否生成HTML格式文档
GENERATE_HTMLHELP NO 是否生成压缩HTML格式文档（.chm）
GENERATE_LATEX YES 是否乘车latex格式的文档
GENERATE_RTF NO 是否生成RTF格式的文档
GENERATE_MAN NO 是否生成man格式文档
GENERATE_XML NO 是否生成XML格式文档
  

3. doxygen注释
3.1 注释风格
下面是工作量最大部分，安装doxygen格式写注释。通常代码可以附上一个注释块来对代码进行解释，一个注释块由一行或者多行组成。通常一个注释块包括一个简要说明（brief）和一个详细说明（detailed），这两部分都是可选的。可以有多种方式标识出doxygen可识别的注释块。
1）JavaDoc类型的多行注释。
/**
 *  ….text….
 */
2）QT样式的多行注释。
/*!
….text….
 */
3） /// …text….
4） //! …text….
简要说明有多种方式标识，这里推荐使用@brief命令强制说明，例如：
/**
 * @brief [some brief description ]
 *      [ brief description more. ]
 *
 * [some more detailed description…]
 */
以上这些注释格式用来对紧跟其后的代码进行注释。doxygen也允许把注释放到代码后面，具体格式是放一个'<'到注释开始部分。例如：
int var1 ; /**< ….text…. */
int var2; ///< ….text….

注释和代码完全分离，放在其他地方也是允许的，但需要使用特殊的命令加上名称或者声明进行标识，比如：class、struct、union、enum、fn、var、def、file、namespace、package、interface（这些也就是doxygen关注的注释类型）。这里不推荐使用，建议注释尽量放在代码前后。具体使用方式参见doxygen手册。

3.2 doxygen常用注释格式
通常的选择上面的一、两种注释风格，遇到头文件中各种类型定义，关键变量、宏的定义，在其前或者后使用 @brief 定义其简要说明，空一行后继续写其详细的注释即可。

对函数的注释，是比较常常需要注释的部分。除了定义其简要说明以及详细注释，还可以使用param命令对其各个参数进行注释，使用return命令对返回值进行注释。常见的格式如下：
/**
 *@brief func's brief comment.
 *
 * Some detailed comment.
 *@param a [param a 's comment.]
 *@param b [param b 's comment.]
 *@exception std::out_of_range [exception's comment.]
 *@return [return's comment.]
 */
int func1(int a, int b);

进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个group。
/** [group_name] [brief group description ]
 * detailed group description ]
 * @{
*/
code
/** @} */
group中的代码可以有自己的注释。单纯定义一个模块，去除{ 和}命令即可。任何其他代码项（比如类、函数、甚至文件）如果要加入到某个模块，可以在其doxygen注释中使用ingroup命令即可。Group之间使用ingroup命令，可以组成树状关系。
/** @file util.cpp
* @ingroup [group_name]
 * @brief file's brief info.
 */
把多个代码项一起添加到某个模块中可以使用addtogroup命令，格式和defgroup相似。

对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式：
//@{
/** Comments for all below code. */
code…
//@}
对这种组进行命名可以使用name命令。此时中间代码可以有自己的注释。如：
/** @name group_name
 * description for group.
 */
//@{
code…
//@}

3.3 doxygen常用注释命令
doxygen通过注释命令识别注释中需要特殊处理的注释，比如函数的参数、返回值进行突出显示。上面也提到了一些注释命令（如：brief、param、return、以及group相关的命令），下面对其他一些常用的注释命令进行解释说明。
@exception <exception-object> {exception description} 对一个异常对象进行注释。
@warning {warning message } 一些需要注意的事情
@todo { things to be done }  对将要做的事情进行注释
@see {comment with reference to other items } 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。
@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since {text} 通常用来说明从什么版本、时间写此部分代码。
@deprecated
@pre { description of the precondition } 用来说明代码项的前提条件。
@post { description of the postcondition } 用来说明代码项之后的使用条件。
@code 在注释中开始说明一段代码，直到@endcode命令。
@endcode 注释中代码段的结束。

到此为止，常用的doxygen的注释格式讨论完毕，我们能够按照一定的格式撰写doxygen认识的注释，并能够使用doxygen方便快捷的生成对应的文档，不过注释中应该写些什么，如何撰写有效的注释可能是困扰开发人员的一个更深层次的问题。

4. 注释的书写
注释应该怎么写，写多还是写少。过多的注释甚至会干扰对代码的阅读。写注释的一个总的原则就是注释应该尽量用来表明作者的意图，至少也应该是对一部分代码的总结，而不应该是对代码的重复或者解释。对代码的重复或者解释的代码，看代码可能更容易理解。反映作者意图的注释解释代码的目的，从解决问题的层次上进行注释，而代码总结性注释则是从问题的解答的层次上进行注释。

推荐的写注释的过程是首先使用注释勾勒出代码的主要框架，然后根据注释撰写相应的代码。对各种主要的数据结构、输出的函数、多个函数公用的变量进行详细地注释。对代码中控制结构，单一目的的语句集进行注释。下面是一些写注释时需要注意的要点：
  避免对单独语句进行注释；
  通过注释解释为什么这么做、或者要做什么，使代码的读者可以只阅读注释理解代码；
  对读者可能会有疑问的地方进行注释；
  对数据定义进行注释，而不是对其使用过程进行注释；
  对于难于理解的代码，进行改写，而不要试图通过注释加以说明；
  对关键的控制结构进行注释；
  对数据和函数的边界、使用前提等进行注释；

5. 参考资料
 1. doxygen homepage
 http://www.stack.nl/~dimitri/doxygen/

 2. doxygen manual
 http://www.stack.nl/~dimitri/doxygen/manual.html

 3. Code Complete: A Practical Handbook of Software Construction. Redmond, Wa.: Microsoft Press, 880 pages, 1993. ISBN: 1-55615-484-4.
 
 4. 简介doxygen
 http://www.stack.nl/~dimitri/doxygen/doxygen_intro_cn.html
 
 5. 10 Minutes to document your code
 http://www.codeproject.com/tips/doxysetup.asp

 6. 使用doxygen
 http://www.csdn.net/Develop/article/16%5C16383.shtm

 
6. 关于作者
mounton @ {www.ihere.org} 当前关注于网络安全产品的开发、研究；软件开发过程等方面。您可以通过mount0n@yahoo.com和他联系。

http://skazami.web.infoseek.co.jp/tools/Graphviz_Doxygen.htm




コードの構造を視覚化するためのツールです。コード解析に有効かどうかはともかく、なかなか面白いツールです。

それぞれのツールのサイト（たぶん、公式サイト）はこちら。

Graphviz
Doxygen

どちらもオープンソースですので、開発に参加することもできるようです。Doxygenは寄付も受け付けているようです。

前置きはこのくらいにして、説明いきます。

インストール

自分のプラットフォームにあったパッケージをダウンロードします。Linux用、Windows用、Mac用などあります。

Graphvizは、上記サイト内にあるdownloadをクリックして、パッケージを持ってきます。
Doxygenも、上記サイトの右のほうにあるBinariesをクリックして、パッケージを持ってきます。

インストールは必ずGraphviz→Doxygenの順番で行います。

以下の説明はWindows用についてのものです。
インストールはインストーラ（exeファイル）を起動してウィザードに従うだけなので、悩むこともないと思います。

ステップバイステップインストール手順（Graphviz、Doxygen）

インストール慣れしている方はスキップしてください。ほとんどデフォルトでのインストールですので。どちらかと言うと、自分用作業メモです。

使用法

1. インストール時に入れておいた「doxygen example Project」を例にコードの構造を視覚化してみます
2. 「スタート」→「プログラム」→「doxygen」→「Doxywizard」を起動します。このツールにより、設定ファイルの作成とDoxygenの実行をGUIから行うことができます。

   
   

3. OUTPUT_LANGUAGEを「Japanese」にします

   
   

4. Buildタブをクリックし、「EXTRACT_ALL」にチェックを入れます

   
   

5. LaTeXタブをクリックし、「GENERATE_LATEX」のチェックを外します。もちろん、LaTeXの出力が必要ならチェックを入れておいてください

   
   

6. Dotタブをクリックし、「HAVE_DOT」にチェックを入れます

   
   

7. 「CALL_GRAPH」にもチェックを入れときます。関数の呼び出し状況を図にしてくれます。

   
   

8. 「File」→「Save as...」で設定ファイルを保存しますが、保存先は「C:\Program Files\doxygen\examples」（デフォルト設定でインストールした場合）としてください。ファイル名は何でもいいですが、とりあえず「Doxyfile」とでもしておきましょう

   
   

9. 「Doxygen」→「Run」で実行します。コンソールが出現し、処理が進みます

   

10. 「C:\Program Files\doxygen\examples」にhtmlというフォルダが作成されます。そのフォルダの中のindex.htmlを開いてみます

    
    
    どうでしょう、こんな画面になりましたか？

11. 「ファイル一覧」→example_test.cppを開いてみてください。関数の呼び出しグラフが表示されましたか？グラフがクリッカブルマップになっていますか？
12. 「ファイル一覧」→diagrams_a.hを開いてみてください。ファイルの依存関係のグラフが表示されましたか？グラフがクリッカブルマップになっていますか？

問題がなければ、基本的な使い方は以上です。あとはマニュアルを読みながら高度な使い方を模索してください。私自身、あまり高度な使い方はできていないので、面白い使い方があったら教えていただきたいです。

Doxygenのマニュアルを日本語化している方がいらっしゃるようです。
http://www.fides.dti.ne.jp/~oka-t/doxygen-manual/html/

Doxygenで変換した結果の例

私が変換してみたものを以下に置いておきます。同じような感じになっているかどうかを確認するために使ってみてください。

doxygen付属のexampleプロジェクト

デフォルト設定で作成直後のWin32アプリケーションプロジェクト（作成環境はVisual Studio .net 2003）

[余談]
doxygenのexampleプロジェクトの変換結果で、「関連ページ」→「バグ一覧」→「WindowsNT」は、あからさま過ぎるくらいあからさまで、まぁまぁ面白いです。これ以上のコメントは控えます。
[余談終]

Doxygen的使用体会

Doxygen是一款开源软件，可用于从已经存在的VC工程中提炼出软件文档（HTML等格式），包括文件说明、类说明、属性方法说明、类关系等内容。一般常将Doxygen和graphviz两款软件一起安装，后者是一款绘图软件，可在前者生成的软件文档中增加图表。Doxygen的细节可以上网搜索。这里贴一下个人体会，可帮助感兴趣的朋友迅速上手这个软件：

1，安装DOXYGEN和graphviz后，可以在“DOXYGEN安装目录\bin”下用命令行方式运行doxygen.exe -g 生成一个名为Doxyfile的配置文件。

2，将文件Doxyfile复制到想生成文档的VC工程目录下。

修改该文件中的如下选项：

查看源代码拷贝至剪贴板打印代码

1. PROJECT_NAME          = 填上项目名称    
2. OUTPUT_LANGUAGE        = 改为Chinese    
3. GENERATE_LATEX        = 改为NO    
4. EXTRACT_ALL            = 改为YES    
5. HAVE_DOT              = 改为YES    
6. DOT_IMAGE_FORMAT      = 该为JPG    
7. DOT_PATH              = 填上"C:/Program Files/ATT/Graphviz/bin/"    
8. DOTFILE_DIRS          = 填上"c:/Program Files/ATT/Graphviz/bin/"   

3，对VC工程进行如下修改

（1）在stdAfx.h中增加预定义，以支持DOT画图。

查看源代码拷贝至剪贴板打印代码

1. #ifndef _DIAGRAMS_A_H    
2. #define _DIAGRAMS_A_H    
3. #endif   

（2）在重要的类、方法、属性前面增加注释，以支持DOXYGEN分析。

查看源代码拷贝至剪贴板打印代码

1. ///    @brief 最主要的业务实现类    
2. ///    
3. ///            所有的算法内容基本都在这个类中实现。    
4. ///    
5. ///    @author lipp   

或者放在语句后面

查看源代码拷贝至剪贴板打印代码

1. char sFilename[400];            ///< LOG文件名   

并在重要文件前增加注释

查看源代码拷贝至剪贴板打印代码

1. ///    @file xxx.cpp    
2. ///    被其他程序调用的，实现了算法的DLL主程序。    
3. ///    包括各个方法输出接口。   

4，运行DOXYGEN.exe。LOAD以上的Doxyfile文件。点击START。这时会生成一个新的HTML目录在VC工程目录中。

5，使用IE打开新生成的HTML目录中的INDEX.htm文件。

　　Makefile的基本结构不是很复杂，但当一个程序开发人员开始写Makefile时，经常会怀疑自己写的是否符合惯例，而且自己写的Makefile经常和自己的开发环境相关联，当系统环境变量或路径发生了变化后，Makefile可能还要跟着修改。这样就造成了手工书写Makefile的诸多问题，automake恰好能很好地帮助我们解决这些问题。

　　使用automake，程序开发人员只需要写一些简单的含有预定义宏的文件，由autoconf根据一个宏文件生成configure，由automake根据另一个宏文件生成Makefile.in，再使用configure依据Makefile.in来生成一个符合惯例的Makefile。下面我们将详细介绍Makefile的automake生成方法。

　　二、使用的环境

　　本文所提到的程序是基于Linux发行版本：Fedora Core release 1，它包含了我们要用到的autoconf，automake。

　　三、从helloworld入手

　　我们从大家最常使用的例子程序helloworld开始。

　　下面的过程如果简单地说来就是：

　　新建三个文件：

　　　helloworld.c
　　　configure.in
　　　Makefile.am

　　然后执行：

aclocal; autoconf; automake --add-missing; ./configure; make; ./helloworld

　　就可以看到Makefile被产生出来，而且可以将helloworld.c编译通过。

　　很简单吧，几条命令就可以做出一个符合惯例的Makefile，感觉如何呀。

　　现在开始介绍详细的过程：

　　1、建目录

　　在你的工作目录下建一个helloworld目录，我们用它来存放helloworld程序及相关文件，如在/home/my/build下：

$ mkdir helloword
$ cd helloworld

　　2、 helloworld.c

　　然后用你自己最喜欢的编辑器写一个hellowrold.c文件，如命令：vi helloworld.c。使用下面的代码作为helloworld.c的内容。

int main(int argc, char** argv)
{
printf("Hello, Linux World!\n");
return 0;
}

　　完成后保存退出。

　　现在在helloworld目录下就应该有一个你自己写的helloworld.c了。

　　3、生成configure

　　我们使用autoscan命令来帮助我们根据目录下的源代码生成一个configure.in的模板文件。

　　命令：

$ autoscan
$ ls
configure.scan helloworld.c

　　执行后在hellowrold目录下会生成一个文件：configure.scan，我们可以拿它作为configure.in的蓝本。

　　现在将configure.scan改名为configure.in，并且编辑它，按下面的内容修改，去掉无关的语句：

============================configure.in内容开始=========================================
# -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.

AC_INIT(helloworld.c)
AM_INIT_AUTOMAKE(helloworld, 1.0)

# Checks for programs.
AC_PROG_CC

# Checks for libraries.

# Checks for header files.

# Checks for typedefs, structures, and compiler characteristics.

# Checks for library functions.
AC_OUTPUT(Makefile)
============================configure.in内容结束=========================================

　　然后执行命令aclocal和autoconf，分别会产生aclocal.m4及configure两个文件：

$ aclocal
$ls
aclocal.m4 configure.in helloworld.c
$ autoconf
$ ls
aclocal.m4 autom4te.cache configure configure.in helloworld.c

　　大家可以看到configure.in内容是一些宏定义，这些宏经autoconf处理后会变成检查系统特性、环境变量、软件必须的参数的shell脚本。

　　autoconf 是用来生成自动配置软件源代码脚本（configure）的工具。configure脚本能独立于autoconf运行，且在运行的过程中，不需要用户的干预。

　　要生成configure文件，你必须告诉autoconf如何找到你所用的宏。方式是使用aclocal程序来生成你的aclocal.m4。

　　aclocal根据configure.in文件的内容，自动生成aclocal.m4文件。aclocal是一个perl 脚本程序，它的定义是：“aclocal - create aclocal.m4 by scanning configure.ac”。

　　autoconf从configure.in这个列举编译软件时所需要各种参数的模板文件中创建configure。

　　autoconf需要GNU m4宏处理器来处理aclocal.m4，生成configure脚本。

　　m4是一个宏处理器。将输入拷贝到输出，同时将宏展开。宏可以是内嵌的，也可以是用户定义的。除了可以展开宏，m4还有一些内建的函数，用来引用文件，执行命令，整数运算，文本操作，循环等。m4既可以作为编译器的前端，也可以单独作为一个宏处理器。

4、新建Makefile.am

　　新建Makefile.am文件，命令：

$ vi Makefile.am

　　内容如下:

AUTOMAKE_OPTIONS=foreign
bin_PROGRAMS=helloworld
helloworld_SOURCES=helloworld.c

　　automake会根据你写的Makefile.am来自动生成Makefile.in。

　　Makefile.am中定义的宏和目标,会指导automake生成指定的代码。例如，宏bin_PROGRAMS将导致编译和连接的目标被生成。

　　5、运行automake

　　命令：

$ automake --add-missing
configure.in: installing `./install-sh'
configure.in: installing `./mkinstalldirs'
configure.in: installing `./missing'
Makefile.am: installing `./depcomp'

　　automake会根据Makefile.am文件产生一些文件，包含最重要的Makefile.in。

　　6、执行configure生成Makefile

$ ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
checking for gcc... gcc
checking for C compiler default output... a.out
checking whether the C compiler works... yes
checking whether we are cross compiling... no
checking for suffix of executables...
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ANSI C... none needed
checking for style of include used by make... GNU
checking dependency style of gcc... gcc3
configure: creating ./config.status
config.status: creating Makefile
config.status: executing depfiles commands
$ ls -l Makefile
-rw-rw-r-- 1 yutao yutao 15035 Oct 15 10:40 Makefile

你可以看到，此时Makefile已经产生出来了。

7、使用Makefile编译代码

$ make
if gcc -DPACKAGE_NAME="" -DPACKAGE_TARNAME="" -DPACKAGE_VERSION="" -

DPACKAGE_STRING="" -DPACKAGE_BUGREPORT="" -DPACKAGE="helloworld" -DVERSION="1.0"

-I. -I. -g -O2 -MT helloworld.o -MD -MP -MF ".deps/helloworld.Tpo" \
-c -o helloworld.o `test -f 'helloworld.c' || echo './'`helloworld.c; \
then mv -f ".deps/helloworld.Tpo" ".deps/helloworld.Po"; \
else rm -f ".deps/helloworld.Tpo"; exit 1; \
fi
gcc -g -O2 -o helloworld helloworld.o 

　　运行helloworld

$ ./helloworld
Hello, Linux World!

　　这样helloworld就编译出来了，你如果按上面的步骤来做的话，应该也会很容易地编译出正确的helloworld文件。你还可以试着使用一些其他的make命令，如make clean，make install，make dist，看看它们会给你什么样的效果。感觉如何？自己也能写出这么专业的Makefile，老板一定会对你刮目相看。

　　四、深入浅出

　　针对上面提到的各个命令，我们再做些详细的介绍。

　　1、 autoscan

　　autoscan是用来扫描源代码目录生成configure.scan文件的。autoscan可以用目录名做为参数，但如果你不使用参数的话，那么autoscan将认为使用的是当前目录。autoscan将扫描你所指定目录中的源文件，并创建configure.scan文件。

　　2、 configure.scan

　　configure.scan包含了系统配置的基本选项，里面都是一些宏定义。我们需要将它改名为configure.in

　　3、 aclocal

　　aclocal是一个perl 脚本程序。aclocal根据configure.in文件的内容，自动生成aclocal.m4文件。aclocal的定义是：“aclocal - create aclocal.m4 by scanning configure.ac”。

　　4、 autoconf

　　autoconf是用来产生configure文件的。configure是一个脚本，它能设置源程序来适应各种不同的操作系统平台，并且根据不同的系统来产生合适的Makefile，从而可以使你的源代码能在不同的操作系统平台上被编译出来。

　　configure.in文件的内容是一些宏，这些宏经过autoconf 处理后会变成检查系统特性、环境变量、软件必须的参数的shell脚本。configure.in文件中的宏的顺序并没有规定，但是你必须在所有宏的最前面和最后面分别加上AC_INIT宏和AC_OUTPUT宏。

　　在configure.ini中：

　　#号表示注释，这个宏后面的内容将被忽略。

　　AC_INIT(FILE)

　　这个宏用来检查源代码所在的路径。

AM_INIT_AUTOMAKE(PACKAGE, VERSION) 

　　 这个宏是必须的，它描述了我们将要生成的软件包的名字及其版本号：PACKAGE是软件包的名字，VERSION是版本号。当你使用make dist命令时，它会给你生成一个类似helloworld-1.0.tar.gz的软件发行包，其中就有对应的软件包的名字和版本号。

AC_PROG_CC

　　这个宏将检查系统所用的C编译器。

AC_OUTPUT(FILE)

　　这个宏是我们要输出的Makefile的名字。

　　我们在使用automake时，实际上还需要用到其他的一些宏，但我们可以用aclocal 来帮我们自动产生。执行aclocal后我们会得到aclocal.m4文件。

　　产生了configure.in和aclocal.m4 两个宏文件后，我们就可以使用autoconf来产生configure文件了。

　　5、 Makefile.am

　　Makefile.am是用来生成Makefile.in的，需要你手工书写。Makefile.am中定义了一些内容：

AUTOMAKE_OPTIONS

　　这个是automake的选项。在执行automake时，它会检查目录下是否存在标准GNU软件包中应具备的各种文件，例如AUTHORS、ChangeLog、NEWS等文件。我们将其设置成foreign时，automake会改用一般软件包的标准来检查。

bin_PROGRAMS

　　这个是指定我们所要产生的可执行文件的文件名。如果你要产生多个可执行文件，那么在各个名字间用空格隔开。

helloworld_SOURCES

　　这个是指定产生“helloworld”时所需要的源代码。如果它用到了多个源文件，那么请使用空格符号将它们隔开。比如需要helloworld.h，helloworld.c那么请写成helloworld_SOURCES= helloworld.h helloworld.c。

　　如果你在bin_PROGRAMS定义了多个可执行文件，则对应每个可执行文件都要定义相对的filename_SOURCES。

　　6、 automake

　　我们使用automake --add-missing来产生Makefile.in。

　　选项--add-missing的定义是“add missing standard files to package”，它会让automake加入一个标准的软件包所必须的一些文件。

　　我们用automake产生出来的Makefile.in文件是符合GNU Makefile惯例的，接下来我们只要执行configure这个shell 脚本就可以产生合适的 Makefile 文件了。

　　7、 Makefile

　　在符合GNU Makefiel惯例的Makefile中，包含了一些基本的预先定义的操作：

make

　　根据Makefile编译源代码，连接，生成目标文件，可执行文件。

make clean

　　清除上次的make命令所产生的object文件（后缀为“.o”的文件）及可执行文件。

make install

　　将编译成功的可执行文件安装到系统目录中，一般为/usr/local/bin目录。

make dist

　　产生发布软件包文件（即distribution package）。这个命令将会将可执行文件及相关文件打包成一个tar.gz压缩的文件用来作为发布软件的软件包。

　　它会在当前目录下生成一个名字类似“PACKAGE-VERSION.tar.gz”的文件。PACKAGE和VERSION，是我们在configure.in中定义的AM_INIT_AUTOMAKE(PACKAGE, VERSION)。

make distcheck

　　生成发布软件包并对其进行测试检查，以确定发布包的正确性。这个操作将自动把压缩包文件解开，然后执行configure命令，并且执行make，来确认编译不出现错误，最后提示你软件包已经准备好，可以发布了。

===============================================
helloworld-1.0.tar.gz is ready for distribution
===============================================
make distclean

　　类似make clean，但同时也将configure生成的文件全部删除掉，包括Makefile。

　　五、结束语

　　通过上面的介绍，你应该可以很容易地生成一个你自己的符合GNU惯例的Makefile文件及对应的项目文件。

　　如果你想写出更复杂的且符合惯例的Makefile，你可以参考一些开放代码的项目中的configure.in和Makefile.am文件，比如：嵌入式数据库sqlite，单元测试cppunit。

As more effort is put into annotating programs, better checking results. A representational effort-benefit curve for using Splint is shown in Figure 1.  Splint is designed to be flexible and allow programmers to select appropriate points on the effort-benefit curve for particular projects.  As different checks are turned on and more information is given in code annotations the number of bugs that can be detected increases dramatically.

Problems detected by Splint include:

·      Dereferencing a possibly null pointer (Section 2);

·      Using possibly undefined storage or returning storage that is not properly defined (Section 3);

·      Type mismatches, with greater precision and flexibility than provided by C compilers (Section 4.1–4.2);

·      Violations of information hiding (Section 4.3);

·      Memory management errors including uses of dangling references and memory leaks  (Section 5);

·      Dangerous aliasing (Section 6);

·      Modifications and global variable uses that are inconsistent with specified interfaces (Section 7);

·      Problematic control flow such as likely infinite loops (Section 8.3.1), fall through cases or incomplete switches (Section 8.3.2), and suspicious statements (Section 8.4);

·      Buffer overflow vulnerabilities (Section 9);

·      Dangerous macro implementations or invocations (Section 11); and

·      Violations of customized naming conventions.  (Section 12).

Figure 1.  Typical Effort-Benefit Curve

Splint checking can be customized to select what classes of errors are reported using command line flags and stylized comments in the code.  In addition, users can define new annotations and associated checks to extend Splint’s checking or to enforce application specific properties (Section 10).

About This Document

This document is a guide to using Splint.  Section 1 explains how to run Splint, interpret messages and control checking.  Sections 2–13 describe particular checks done by Splint.  There are some minor dependencies between sections, but in general they can be read in any order.  Section 14 covers issues involving libraries and header file inclusion important for running Splint on large systems.

This document does not describe technical details of the checking.  For technical background and analysis of Splint’s effectiveness in practice, see the papers available at http://www.splint.org. 

static (Global) Function: 有文件作用域，只在本文件中使用
Global Function:无文件作用域

static Member (in Function) variable:函数调用完成后，变量保存状态，再次调用函数，不会重新分配空间
Member(in Funcition) variable:函数内的生命周期

static Member(in Class) variable: 属于类范围，
Member(in Class) variable:属于类派生的特定对象，生命周期和对象一致

/*
 * Copyright 2005, XX, Inc., China
 * All rights reserved.
 *
 * XX's source code is an unpublished work and the use of a copyright notice does
 * not imply otherwise. This source code contains confidential, trade secret material of
 * XX, Inc. Any attempt or participation in deciphering, decoding, reverse engineering
 * or in any way altering the source code is strictly prohibited, unless the prior written
 * consent of XX, Inc. is obtained.
 */

/*
 * @file ANSI_C_CODING_STANDARDS.h
 * @author tony_bai
 * @date 2005-07-01
 * @brief the template for ANSI C
 *        header file
 */

/*
 * @revision
 *   @version 0.1
 *   @date 2005-08-01
 *   @Revisor tony_bai
 *  
 * @revision
 *   @version 0.2
 *   @date 2005-09-01
 *   @Revisor tony_bai
 */

/*
 * @glossary
 *   xx - xxxxx
 *   xx - xxxxx
 */

/*
 * @usage
 *
 */

#ifndef ANSI_C_CODING_STANDARDS_H
#define ANSI_C_CODING_STANDARDS_H

#include <ANSI C Standard Library Header File>
#include <Operating System Library Header File>
#include "Your System Library Header File"

/*
 * ####################
 * # global constants #
 * ####################
 */

/*
 * #################
 * # global macros #
 * #################
 */

/*
 * ##############################
 * # global abstract data types #
 * ##############################
 */

/*
 * ####################
 * # global variables #
 * ####################
 */

/*
 * #############
 * # externals #
 * #############
 */

/*
 * ###############################
 * # global functions prototypes #
 * ###############################
 */

#endif ANSI_C_CODING_STANDARDS_H

//in ANSI_C_CODING_STANDARDS.c

/*
 * Copyright 2005, XX, Inc., China
 * All rights reserved.
 *
 * XX's source code is an unpublished work and the use of a copyright notice does
 * not imply otherwise. This source code contains confidential, trade secret material of
 * XX, Inc. Any attempt or participation in deciphering, decoding, reverse engineering
 * or in any way altering the source code is strictly prohibited, unless the prior written
 * consent of XX, Inc. is obtained.
 */

/*
 * @file ANSI_C_CODING_STANDARDS.c
 * @author tony_bai
 * @date 2005-07-01
 * @brief the template for ANSI C
 *        source file
 */

/*
 * @revision
 *   @version 0.1
 *   @date 2005-08-01
 *   @Revisor tony_bai
 *  
 * @revision
 *   @version 0.2
 *   @date 2005-09-01
 *   @Revisor tony_bai
 */

#include <ANSI C Standard Library Header File>
#include <Operating System Library Header File>
#include "Your System Library Header File"

/*
 * ###################
 * # local constants #
 * ###################
 */

/*
 * ################
 * # local macros #
 * ################
 */

/*
 * #############################
 * # local abstract data types #
 * #############################
 */

/*
 * ###################
 * # local variables #
 * ###################
 */

/*
 * ##############################
 * # local functions prototypes #
 * ##############################
 */

/*
 * ####################################
 * # global functions implementations #
 * ####################################
 */

/*
 * ###################################
 * # local functions implementations #
 * ###################################
 */

要想读懂本文，你需要对C语言有基本的了解，本文将介绍如何使用gcc编译器。首先，我们介绍如何在命令行方式下使用编译器编译简单的C源代码。然后，我们简要介绍一下编译器究竟作了那些工作，以及如何控制编译过程。我们也简要介绍了调试器的使用方法。

 

GCC rules

你能想象使用封闭源代码的私有编译器编译自由软件吗？你怎么知道编译器在你的可执行文件中加入了什么？可能会加入各种后门和木马。Ken Thompson是一个著名的黑客，他编写了一个编译器，当编译器编译自己时，就在'login'程序中留下后门和永久的木马。请到 这里 阅读他对这个杰作的描述。幸运的是，我们有了gcc。当你进行 configure; make; make install 时， gcc在幕后做了很多繁重的工作。如何才能让gcc为我们工作呢？我们将开始编写一个纸牌游戏，不过我们只是为了演示编译器的功能，所以尽可能地精简了代码。我们将从头开始一步一步地做，以便理解编译过程，了解为了制作可执行文件需要做些什么，按什么顺序做。我们将看看如何编译C程序，以及如何使用编译选项让gcc按照我们的要求工作。步骤（以及所用工具）如下： 预编译 (gcc -E)， 编译 (gcc)， 汇编 (as)，和 连接 (ld)。

开始...

首先，我们应该知道如何调用编译器。实际上，这很简单。我们将从那个著名的第一个C程序开始。（各位老前辈，请原谅我）。

#include <stdio.h>
int main()

{
printf("Hello World!\n");
}

把这个文件保存为 game.c。 你可以在命令行下编译它：

gcc game.c

a.out
Hello World

gcc -o game game.c

game
Hello World

到现在为止，我们离一个有用的程序还差得很远。如果你觉得沮丧，你可以想一想我们已经编译并运行了一个程序。因为我们将一点一点为这个程序添加功能，所以我们必须保证让它能够运行。似乎每个刚开始学编程的程序员都想一下子编一个1000行的程序，然后一次修改所有的错误。没有人，我是说没有人，能做到这个。你应该先编一个可以运行的小程序，修改它，然后再次让它运行。这可以限制你一次修改的错误数量。另外，你知道刚才做了哪些修改使程序无法运行，因此你知道应该把注意力放在哪里。这可以防止这样的情况出现：你认为你编写的东西应该能够工作，它也能通过编译，但它就是不能运行。请切记，能够通过编译的程序并不意味着它是正确的。

下一步为我们的游戏编写一个头文件。头文件把数据类型和函数声明集中到了一处。这可以保证数据结构定义的一致性，以便程序的每一部分都能以同样的方式看待一切事情。

#ifndef DECK_H
#define DECK_H
#define DECKSIZE 52
typedef struct deck_t
{
int card[DECKSIZE];
/* number of cards used */
int dealt;
}deck_t;
#endif /* DECK_H */

把这个文件保存为 deck.h。只能编译 .c 文件，所以我们必须修改 game.c。在game.c的第2行，写上 #include "deck.h"。在第5行写上 deck_t deck;。为了保证我们没有搞错，把它重新编译一次。

gcc -o game game.c

如果没有错误，就没有问题。如果编译不能通过，那么就修改它直到能通过为止。

预编译

编译器是怎么知道 deck_t 类型是什么的呢？因为在预编译期间，它实际上把"deck.h"文件复制到了"game.c"文件中。源代码中的预编译指示以"#"为前缀。你可以通过在gcc后加上 -E 选项来调用预编译器。

gcc -E -o game_precompile.txt game.c
wc -l game_precompile.txt
3199 game_precompile.txt

1. 把"include"的文件拷贝到要编译的源文件中。
2. 用实际值替代"define"的文本。
3. 在调用宏的地方进行宏替换。

编译

作为一个中间步骤，gcc把你的代码翻译成汇编语言。它一定要这样做，它必须通过分析你的代码搞清楚你究竟想要做什么。如果你犯了语法错误，它就会告诉你，这样编译就失败了。人们有时会把这一步误解为整个过程。但是，实际上还有许多工作要gcc去做呢。

汇编

as 把汇编语言代码转换为目标代码。事实上目标代码并不能在CPU上运行，但它离完成已经很近了。编译器选项 -c 把 .c 文件转换为以 .o 为扩展名的目标文件。 如果我们运行

gcc -c game.c

#include <stdlib.h>
#include <stdio.h>
#include <time.h>
#include "deck.h"
static time_t seed = 0;
void shuffle(deck_t *pdeck)
{
/* Keeps track of what numbers have been used */
int drawn[DECKSIZE] = {0};
int i;
/* One time initialization of rand */
if(0 == seed)
{
seed = time(NULL);
srand(seed);
}
for(i = 0; i < DECKSIZE; i++)
{
int value = -1;
do
{
value = rand() % DECKSIZE;
}
while(drawn[value] != 0);
/* mark value as used */
drawn[value] = 1;
/* debug statement */
printf("%i\n", value);
pdeck->card[i] = value;
}
pdeck->dealt = 0;
return;
}

把这个文件保存为 shuffle.c。我们在这个代码中加入了一条调试语句，以便运行时，能输出所产生的牌号。这并没有为我们的程序添加功能，但是现在到了关键时刻，我们看看究竟发生了什么。因为我们的游戏还在初级阶段，我们没有别的办法确定我们的函数是否实现了我们要求的功能。使用那条printf语句，我们就能准确地知道现在究竟发生了什么，以便在开始下一阶段之前我们知道牌已经洗好了。在我们对它的工作感到满意之后，我们可以把那一行语句从代码中删掉。这种调试程序的技术看起来很粗糙，但它使用最少的语句完成了调试任务。以后我们再介绍更复杂的调试器。

1. 我们用传址方式传递参数，你可以从'&'（取地址）操作符看出来。这把变量的机器地址传递给了函数，因此函数自己就能改变变量的值。也可以使用全局变量编写程序，但是应该尽量少使用全局变量。指针是C的一个重要组成部分，你应该充分地理解它。
2. 我们在一个新的 .c 文件中使用函数调用。操作系统总是寻找名为'main'的函数，并从那里开始执行。 shuffle.c 中没有'main'函数，因此不能编译为独立的可执行文件。我们必须把它与另一个具有'main'函数并调用'shuffle'的程序组合起来。

运行命令

gcc -c shuffle.c

shuffle(&deck);

gcc -o game game.c
/tmp/ccmiHnJX.o: In function `main':
/tmp/ccmiHnJX.o(.text+0xf): undefined reference to `shuffle'
collect2: ld returned 1 exit status

连接

连接器ld，使用下面的命令，接受前面由 as 创建的目标文件并把它转换为可执行文件

gcc -o game game.o shuffle.o

连接器从shuffle.o目标文件中找到 shuffle 函数，并把它包括进可执行文件。目标文件的真正好处在于，如果我们想再次使用那个函数，我们所要做的就是包含"deck.h" 文件并把 shuffle.o 目标文件连接到新的可执行文件中。

象这样的代码重用是经常发生的。虽然我们并没有编写前面作为调试语句调用的 printf 函数，连接器却能从我们用 #include <stdlib.h> 语句包含的文件中找到它的声明，并把存储在C库（/lib/libc.so.6）中的目标代码连接进来。这种方式使我们可以使用已能正确工作的其他人的函数，只关心我们所要解决的问题。这就是为什么头文件中一般只含有数据和函数声明，而没有函数体。一般，你可以为连接器创建目标文件或函数库，以便连接进可执行文件。我们的代码可能产生问题，因为在头文件中我们没有放入任何函数声明。为了确保一切顺利，我们还能做什么呢？

另外两个重要选项

-Wall 选项可以打开所有类型的语法警告，以便帮助我们确定代码是正确的，并且尽可能实现可移植性。当我们使用这个选项编译我们的代码时，我们将看到下述警告：

game.c:9: warning: implicit declaration of function `shuffle'

void shuffle(deck_t *pdeck);

另一个常用编译器选项是优化选项 -O# (即 -O2)。 这是告诉编译器你需要什么级别的优化。编译器具有一整套技巧可以使你的代码运行得更快一点。对于象我们这种小程序，你可能注意不到差别，但对于大型程序来说，它可以大幅度提高运行速度。你会经常碰到它，所以你应该知道它的意思。

调试

我们都知道，代码通过了编译并不意味着它按我们得要求工作了。你可以使用下面的命令验证是否所有的号码都被使用了

game | sort - n | less

gcc -g -c shuffle.c game.c
gcc -g -o game game.o shuffle.o

小结

本文大体介绍了编译和调试C程序的方法。我们讨论了编译器走过的步骤，以及为了让编译器做这些工作应该给gcc传递哪些选项。我们简述了有关连接共享函数库的问题，最后介绍了调试器。真正了解你所从事的工作还需要付出许多努力，但我希望本文能让你正确地起步。你可以在 gcc、 as 和 ld的 man 和 info page中找到更多的信息。

自己编写代码可以让你学到更多的东西。作为练习你可以以本文的纸牌游戏为基础，编写一个21点游戏。那时你可以学学如何使用调试器。使用GUI的KDbg开始可以更容易一些。如果你每次只加入一点点功能，那么很快就能完成。切记，一定要保持程序一直能运行！

要想编写一个完整的游戏，你需要下面这些内容：

• 一个纸牌玩家的定义（即，你可以把deck_t定义为player_t）。
• 一个给指定玩家发一定数量牌的函数。记住在纸牌中要增加“已发牌”的数量，以便能知道还有那些牌可发。还要记住玩家手中还有多少牌。
• 一些与用户的交互，问问玩家是否还要另一张牌。
• 一个能打印玩家手中的牌的函数。 card 等于value % 13 （得数为0到12），suit 等于 value / 13 （得数为0到3）。
• 一个能确定玩家手中的value的函数。Ace的value为零并且可以等于1或11。King的value为12并且可以等于10。

站点链接

• gcc GCC GNU Compiler Collection
• gdb GNU Debugger
• KDbg KDE's GUI Debugger
• Award Winning Compiler Hack Ken Thompson's great compiler hack