program_format.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"   
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY table-indent-isone SYSTEM "program_indent_isone.xml">
<!ENTITY table-indent-params SYSTEM "program_indent_params.xml">
]-->
<sect1 id="format"><title>格式规范</title>

<sect2 id="general"><title>一般格式原则</title>
<sect3><title>规则</title>
<orderedlist>
<listitem>
<para>缩进用tab，不用空格；
</para>
</listitem>
<listitem>
<para>一个tab定义为四个空格，原因见后面表格；
</para>
</listitem>
<listitem>
<para>标点符号的右边留一个空格（左括号除外）；
</para>
</listitem>
<listitem>
<para>赋值、判断、运算符号两边都要加一个空格；
</para>
</listitem>
<listitem>
<para>空行也是注释，适当的空行使逻辑更清楚，函数内部不应该有连续空行，函数之间至少有两个连续空行；
</para>
</listitem>
</orderedlist>
</sect3>

<sect3><title>实例</title>
<para>
略...
</para>
<!--orderedlist>
<listitem>
<para>
反例：空格缩进
</para>
<mediaobject>
<imageobject>
<imagedata fileref="images/wuzj/1_format-tab-insteadof-space.jpg" format="JPEG">
</imageobject>
<textobject>
<phrase>应该用TAB缩进</phrase>
</textobject>
<caption>
<para>
应该用TAB缩进
</para>
</caption>
</mediaobject>
</listitem>
</orderedlist-->
</sect3>

</sect2>

<sect2><title>变量</title>
<orderedlist>
<listitem>
<para>当出现变量和常量比较和判断时，常量放在左边，以防止"= ="错误输入为"="，时可以由编译器检验；（强制）
</para>
</listitem>
<listitem>
<para>变量定义块分两部分，外部定义在前，且加上extern关键字；
</para>
</listitem>
<listitem>
<para>程序的include 块也分两部分；一部分为包含标准头文件，后一部分为本工程内部定义的头文件；
</para>
</listitem>
</orderedlist>
</sect2>

<sect2><title>函数</title>
<orderedlist>
<listitem>
<para>所有调用函数在".h"头文件中声名，对于只是在本模块中调用的函数，用static关键字限制；
</para>
</listitem>
<listitem>
<para>main函数，一定有返回值，且为int类型；
</para>
</listitem>
<listitem>
<para>函数之间空两行，以示区分；
</para>
</listitem>
<listitem>
<para>函数的类型和函数名分开两行写，即函数类型和函数名都从1列开始；
</para>
<para>
方便使用命令 <command>grep "^函数名" 文件名</command> 快速查找函数定义，而不会定位到函数调用的代码；
</para>
</listitem>
<listitem>
<para>函数的参数一个一行（推荐）；
</para>
</listitem>
<listitem>
<para>一个函数不长于100行左右，即不超过两屏，如果超过，说明应该考虑进一步模块化；
</para>
</listitem>
</orderedlist>
</sect2>

<sect2 id="comment"><title>注释</title>
<para>
应把注释看做和代码一样重要，也要统计到代码量中去。注释除了能够使得代码更易读、清晰外，还能用来生成文档。参见：<ulink url="http://www.doxygen.org/">Doxygen 计划</ulink>。
</para>
<itemizedlist> 
<listitem>
<para>分类</para>
<orderedlist> 
<listitem>
<para>按位置分：
</para>
<para>1. 位于语句后；2. 变量声明后；3. 予处理后；4. 或单独开始的注释（又有是否从第一行开始的区别）。
</para>
</listitem>
<listitem>
<para>按照形式分：
</para>
<para>块注释；单行注释（又有是否独立一行或者在代码后面的区别）。
</para>
<para>块注释（boxed comments）：Boxed  comments  are defined as those in which the initial `/*' is followed immediately by the character `*', `=', `_', or `-', or those in which the beginning comment delimiter (`/*') is on a line by itself, and  the following line begins with a `*' in the same column as the star of the opening delimiter.
</para>
</listitem>
<listitem>
<para>以上各个类型的注释可以被indent工具区分和格式化；indent忽略块注释，对齐单行注释等等；
</para>
</listitem>
</orderedlist>
<tip>
<para>
For larger blocks of code that I want to comment and un-comment regularly (eg, debug code), 
I like to use comments in this style:
</para>
<screen>
/* debug code ------------- //
 echo "This is debug code";
 ...
// ---------------------- */
</screen>
<para>
You can easily uncoment the whole block by changing the /* to //, and vice versa.
</para>
</tip>
</listitem>

<listitem>
<para>书写规范</para>
<orderedlist>
<listitem>
<para>可以用c++风格注释"//"，或者用c风格"/*  */"；
</para>
</listitem>
<listitem>
<para>注释最好用英文，英文困难找翻译；
</para>
</listitem>
<listitem>
<para>文件头注释结构：为块注释。参见：<ulink url="http://www.doxygen.org/">Doxygen 的风格</ulink>。
</para>
</listitem>
<listitem>
<para>函数前注释结构：为块注释。注名功能。如果参数名不能表达意义，还要说明参数意义。
</para>
</listitem>
<listitem>
<para>块注释写法：
</para>
<screen>
   /*
    * a space before *
    */
</screen>
<para>或者
</para>
<screen>
   /* have a space after 
      three spaces before  */
</screen>
</listitem>
</orderedlist>
</listitem>
</itemizedlist>
</sect2>

<sect2 id="indent"><title>用 indent 进行代码格式化</title>
<para>
一个范例，胜过前言万语。用 indent 格式化代码，再从格式化前后的格式变化，
来学习格式化规范。
</para>
<para>
可以用不同的参数调用 indent，
</para>
<sect3><title>introduce indent</title>
<orderedlist> 
<listitem>
<para>What is Indent
</para>
<para>The `indent' program can be used to make code easier to read. It can also convert from one style of writing C to another.
</para>
</listitem>
<listitem>
<para>Download
</para>
<para>Current Version: GNU indent 2.2.7。
Download : <ulink url="ftp://ftp.gnu.org/gnu/indent/indent-2.2.7.tar.gz">
ftp.gnu.org/gnu/indent/indent-2.2.7.tar.gz</ulink>
</para>
</listitem>
</orderedlist> 
</sect3>

<sect3 id="indent-opt">
<title>Indent参数规范</title>
<para>我们参照GNU，Kernighan &amp; Ritchie，Berkeley风格，制定了自己风格：
</para>
<orderedlist>
<listitem>
<para>indent命令参数：
</para>
<para>-bad -bap -bbb -bbo -nbc -bl -bli0 -bls -c33 -cd33 -ncdb -ncdw -nce 
 -cli0 -cp33 -cs -d0 -nbfda -di2 -nfc1 -nfca -hnl -ip5 -l75 -lp -pcs -nprs 
 -psl -saf -sai -saw -nsc -nsob -nss -i4 -ts4 -ut
</para>
</listitem>
<listitem>
<para>indent配置文件
</para>
<para>如上参数可写入用户目录下的文件：".indent.pro"，作为运行indent的确省参数。
</para>
</listitem>
<listitem>
<para>indent配置说明
</para>

&table-indent-isone;

</listitem>
</orderedlist>
<para>
indent详细参数以及各种编程排版风格见: <link linkend='appendix-indent'>附录</link>。
</para>
</sect3>

</sect2>

</sect1>