当前位置: 代码迷 >> 综合 >> 一般代码规范,General Regulations for Coding (quanben,2007-3-21试行)
  详细解决方案

一般代码规范,General Regulations for Coding (quanben,2007-3-21试行)

热度:92   发布时间:2023-12-08 19:41:28.0

=== 一般代码规范,General Regulations for Coding (quanben,2007-3-21试行) ===

== 历史 ==
   2007-04-28-09:04,修订,放宽了对数字命名的限制。
   2007-04-18-09:38,增订了一些建议。
   2007-04-04-11:07,“注释”板块增订。
   2007-03-30-14:42,微小修改。
   2007-03-28-22:12,修订。
   2007-03-21-23:12,初订。

== 目的 ==
    规定C/C++的关键字的编码。

== 基本原则 ==
    1. 可分辨,无歧义或无显著的歧义;
    2. 为工程实践提供快速命名指导,且有助于快速输入;
    3. 美观。
   
== 词法评价的几个等级 ==
    1. 合法
       与本规范相容的情形
       1.1 推荐的或可行的
           本规范明确推荐的方法或默许的方法
       1.2 不推荐的
           本规范明确表示不推荐的方法
    2. 非法
       与本规范不相容的情形

== 概念定义 ==
    1. 词元       能表达全部或部分确切含义的不含空格的字符串。
    2. 正规化     将词元转换成目标关键字中的对应子串的过程。后文不加说明,“词元”一般指正规化后的原始词元。
    3. 分解       或叫解析。将目标关键字解释为词元的连接的过程。
    4. 下划线连接 在目标串中相邻词元用下划线连接;“双侧下划线连接”指某词元的两侧如有词元则与之用下划线连接。

== 命名流程 ==
    1. 根据语意构造词元序列,左侧建议采用较大或较重要的概念的词;
    2. 将每个词元正规化;
    3. 从左至右扫描,根据具体连接方案连接各正规概念串为目标串。

== 词元和连接原则 ==

= 强制规则 =
    根据C/C++语法规范,关键词首部不得为数字,因此数字起始的词元不得作为最左词元;
    全小写的词元必须双侧下划线连接;
    相互直接连接的词元的后一个必须是首字母大写;
    词元除首字母外其余字母必须为小写;
    词元最少可以是一个;
    下划线可用于支持词元序列根据含义的划分。

= 建议规则 =
    包含数字的词元建议采用双侧下划线连接;
 对于大写过多的情形,可以寻求词元重组支援,见例2。

= 举例 =
    例1. 类型定义,MyVertex2iStack,分解为My,Vertex2i(2D的整数顶点),Stack。
 例2. 类型定义,MySInt32,分解为My,S(有符号型),Int32,可以将S和Int32合并为一个词元,表示为Sint32,于是可写为MySint32。

= 具体命名方案 ==

= 变量 =
    变量以扩展的骆驼法作为连接方案。变量不允许大写字母起始。
    变量的保留词元包括:
    1. 域说明前缀
       k    常量(规定)
       g    全局,静态的类成员(规定)
       m    非静态的类成员变量(规定)
       v    一般的其他变量,不常用(建议)
    2. 常用的类型说明前缀(建议)
       2.1 强烈建议采用的
           p    指针
           pp   指向指针的指针
           psz  以0结尾的字符串指针(sz则用于字符串数组缓冲)
       2.2 非常建议采用的
           n    整数类型
           i    表示序号索引
           num  表示个数,也可用num of双词元作为前缀;语意和词元count相近。
           id   表示标识
           str  字符串类型(C++)
       2.3 一般建议采用的
           arr  数组,FDC建议使用_arr后缀指明数组。
           上述保留词元必须正规化为小写。
           尽量用一些具有贴切含义的表达,如:
               int studentAgeList[10];     // [:List:]后缀暗示数组,不被FDC建议。
               Box boxes[20];              // 复数暗示数组
           序号一般用i,j,k等。
   
    举例:
        例1,全局的学生姓名(0结尾)字符串数组。词元序列:g,psz,student,names。连接为:p_pszStudentNames。
        例2,全局的x方向Y分量宏块的个数。词元序列:g,mb(macroblock的缩写), cnt(count的缩写), y, x。连接为:g_MbCntY_x。
        例3,ODBC数据接口。词元序列:ODBC,data,interface。连接为:odbcDataInterface。
   
    全小写法是上述规则的一个特例。

    某些场合的可不使用上述命名规范,如常用模板类参照STL规范定义内部变量。

= 函数 =
    函数规则基本和变量一致,只是目标串必须是首字母大写,并且建议以操作对象的类型作为词元序列的首部(概念树的根部)。
    举例:
        学生课程增加函数。词元序列:student,add,course。连接为:Student_AddCourse。(其中Student作为操作对象成为一个相对独立词元)

    例外:对于一些基元应用,函数允许采用全小写,如底层开发,内联函数,某些早期意义的C语言开发,常用模版类(参照STL规范)等。

= 类型 =
    类型规则基本和变量一致,目标串也必须首字母大写。

    举例:
        AVL树。词元序列:AVL,tree,连接为:AvlTree

    类型定义的一般格式,以结构为例:
        typedef struct _AvlTree
        {
            // members
        } AvlTree;

    例外:对于一些基元应用,类型允许采用全小写,但自定义类型建议用_t结尾。如底层开发,某些早期意义的C语言开发,常用模版类(参照STL规范)等。

= 宏定义 =
    宏定义全大写,下划线分割。对于仅作为定义检查的宏定义,采用下划线起始,其余的宏定义不使用下划线起始。
    宏开关(不强烈)建议以_SWITCH结尾。

    例外:允许某些宏函数参照函数命名规则(很不建议),如:
        Endian_U32_BToN   用于将32位无符号大端整数转换为本地整数。(作为参考,Apple的定义为:EndianU32_BtoN)


= 打印信息 =
    起始符号:
        ':' 输出
        '>' 输入
        '!' 错误信息
        '%' 调试信息

= 注释 =
    [::]    关注符号,表示其中内容为对代码内容的引用。也可用`'符号,但不推荐。
    ..    注释内容层次(每层2个句点)
    <>      XML式注释,一般可用于过程级描述。
    ==      注释分段,一般用于文件级描述。
    NTT     Not Thoroughly Tested缩写。
    TODO    工作需求。如:/* TODO: Initialization code here. */

  相关解决方案