源程序文档化

,单击此处编辑母版标题样式,单击此处编辑母版文本样式,第二级,第三级,第四级,第五级,12/16/2014,#,软件工程研讨,源程序文档化,第,六,组,组员：,12122208,陈帅,12123298,马敏,12123249,雷晴,12123256,邱可艺,2014.12.16,变量、常量和函数的命名规范,变量,名所有字母小写，单词之间用下划线,(_),分开，类成员变量以下划线结束,。,普通变量命名,(Common Variable Names),比如：,类数据组成变量命名,(Class Data Members),数据成员（又叫实例变量或者成员变量）的命名与普通变量一样，,全部字母小写，可选的下划线分隔符，但应该以下划线结束。,string table_name_; /,可以以下划线结束,string tablename_; /,可以,变量命名,(Variable Names),string table_name; /,可以使用下划线,string tablename; /,可以全部字母小写,string tableName; /,糟糕大小写混合,结构体成员变量命名,(Struct Variables),结构体成员变量和普通变量命名规则一致，且不像类,成员变量以下划线结束。,struct UrlTableProperties,string name;,int num_entries;,全局变量命名,(Global Variables),全局变量的使用较为罕见，但当用到时，,考虑以前缀,g_,开头或标以其他记号，以便与局部变量区分。,常量命名,(Constant Names),K,后跟混合大小写的名称：,kDaysInAWeek,。所有编译时常量，不管是被声明为局部、全局还是作为类的成员，都应该遵守与其他变量命名有轻微差别的命名约定：,k,后跟单词首字母大写的名称：,const int kDaysInAWeek = 7;,函数命名,(Function Names,),正规函数名应该以大写字母开头，单词首字母大写，不使用下划线。如果函数可能因错误而崩溃，应该在函数名后加上,OrDie,。这仅适用于那些被产品代码调用或者正常操作有可能引起错误的函数。,AddTableEntry(),DeleteUrl(),OpenFileOrDie(),访问器和修改器,(Accessors and Mutators),访问器和修改器（,get,和,set,函数）应该与它们关联的变量名匹配。下面显示了一个类的部分摘录，它有一个实例变量,num_entries,class MyClass,public:,.,int num_entries() constreturn num_entries;,void set_num_entries(int num_entries)num_entries = num_entries;,private:,int num_entries_;,;,你也可以使用小写字母和下划线来命名非常短小的内联函数。比如，如果一个函数的调用开销很小，在循环调用时，没必要缓存其值，这时，小写字母命名是允许的。,对文件、类、函数、变量和逻辑功能段进行注释的规范,文件注释,(File Comments),每个文件都应该提供版权信息，然后是文件内容的综合性描述。,合法公告和作者信息行,(Legal Notice and Author Line),每个文件都应依次包括以下条目,，,1,、,版权,声明,(,比如,Copyright 2008 Google Inc.),；,2,、,一,个许可引用。选择适合你项目使用的许可引用（比如,Apache 2.0,、,BSD,、,LGPL,、,GPL,）,3,、,作者,信息行说明文件原始作者,如果你对原始作者的文件做了实质性修改，可以在作者信息行加上你的名字。当其他开发者有问题时，这样可以方便他们正确地联系到修改者。,文件内容注释,(File Contents),每个文件都应该在其版权信息及作者信息后面和内容前面有一个内容描述性的注释,。,通常，头文件描述它所声明的类的目的及用法。而源文件则应该包含更多有关实现和技巧性算法的讨论信息。但如果你觉得这些信息对于头文件的阅读者更有用，可以将其放在头文件中，但在源文件中应该注明其文档在头文件中。不要在头文件和源文件中重复注释，这样容易造成歧义。,类注释,(Class Comments),每个类定义都应该伴随有说明其目的和用法的注释。,/,遍历,GargantuanTable,的内容。用法示例：,/ GargantuanTableIterator* iter = table-NewIterator();,/ for(iter-seek(“foo”);!iter-done();iter-next(),/ process(iter-key(),iter-value();,/ ,/ delete iter;,Class GargantuanTableIterator,.,如果你在文件开始就已对类进行了详细描述，可以在类实现部分简单地声明“参见文件开始注释部分的完整描述”，但注意，这里还是要添加少量注释。,函数注释,(Function Comments),函数声明部分的注释描述函数的用法，实现部分的注释描述函数实现的操作。,每个函数声明的前面都应该有一个描述函数功能和用法的注释。这些注释应该是描述性,(Opens the file),，而不是祈使性的（,Open the file,），注释仅仅描述函数能够完成什么功能而不是函数是怎么实现的，这些应该在函数实现的注释中。,在函数声明注释中应该提到的信息类型：,1,、,输入,和输出；,2,、,对于,类成员函数，在该方法的调用周期外，对象是否有引用参数，它是否会释放这些引用；,3,、,如果,一个函数申请了内存，它必须释放它们；,4,、,参数,是否可以是空；,5,、,函数,的使用方法是否会影响其性能；,6,、,如果,函数可重入。它是怎么实现同步的？,例子：,/,返回这个表的一个迭代器,/,当遍历结束时，由客户程序负责迭代器的释放,/,一旦此迭代器的创建者,GargantuanTable,对象被释放,/,客户程序不可再使用此迭代器,/,/,迭代器被初始化为指向表的开始,/,/,这个方法等价于：,/ Iterator *iter = table-NewIterator();,iter-seek(“”);,return iter;,/,如果你想立即寻找返回的迭代器中的另一个位置，使用,NewIterator(),更快，而,/,且避免了额外的查找。,Iterator* getIterator()const,然而，避免不必要的冗长注释且不要添加显而易见的注释。比如下例外中，返回假的情况就没必要，因为这很明显：,/,如果表已被占满，不能再容纳实体，则返回真,bool IsTableFull();,当给构造和析构函数加注释时，注意，读者清楚地知道这些函数的作用，所以诸如“销毁这个对象”的注释毫无意义。注释内容应该说明构造函数怎样处理参数（比如它是否取得指针的控制权）和析构函数怎么完成清理工作。如果这些不很重要，可以省略它们。文件的开头注释中没有关于析构函数的注释是很正常的。,函数定义注释,(Function Definition),每个函数都应该有一个注释来描述函数的功能和其完成这些功能的实现技巧（如果有的话）。比如，你在函数定义注释中，你可以描述编码中用到的技巧，给出大致的执行步骤或者解释一下你选择这种实现而不使用其他替代方法的原因。比如，你可能需要说明为什么函数前半部分需要锁而后半部分不需要。,注意，不能简单地重复头文件或者其他地方函数声明部分的注释。可以再次概括一下函数的功能，但焦点应该是函数是怎么实现功能的。,变量注释,(Variable Comments),通常，一个变量的实际名称已经提供了足够和描述信息来说明其用途。但某些情况下，可能需要更多注释。,类数据成员,(Class Data Members,),每个类数据成员（也称实例变量或者成员变量）应该有一个描述其用途的注释。如果这个变量能取得具有特殊意义的标志值，比如,NULL,或,-1,，则需要加以说明。比如：,Private:,/,记录表中实体的总数,/,用于确保不打破数量限制。,/-1,意味着表的实体数未知,int num_total_entries;,全局变量,(Global Variables),和数据成员一样，所有全局变量应该有一个描述其功能及其意义的注释。比如,/,所有本次回归测试使用到的测试用例数,cosnt int kNumTestCases = 6;,实现注释,(Implementation Comments),在实现中，应该对你代码技巧性的、不明显的、有趣的或者重要的部分进行注释。,类数据成员,(Class Data Members),技巧性的和复杂难懂的代码块前应该有注释：,/ Divide result by two, taking into account that x,/ contains the carry from the add,for(int i = 0;i size();i+),x = (x 1;,X ,行注释,(Line Comments),同样，当行代码中有不明显的地方时，也需要在其行末添加注释。这种行末注释应该以,2,个空白与代码分开。,/ If we have enough money, mmap the data portion too.,mmap_budget = max(0,mmap_budget index_-length();,if(mmap_budget = data_size & !mmapData(mmap_chunk_bytes,mlock),return; / Error already logged.,可以看到，这里即有描述代码功能的注释，也有提醒函数返回时错误已经被记录的注释。,如果有多行注释，将它们整齐排列将增加可读性。,DoSomething(); / Comment here so the comments line up,DoSomethingElseThatIsLong(); / Comment here so there are two spaces,/ between the code and the comment,/ One space before commnet when opening a new scope is allowed,/ thus the comment lines up with the following comments and code,DoSomethingElse(); / Two spaces before line comments normally,逻辑功能段进行注释,当给函数传入,NULL,、布尔值和整型值串时，应该增加注释以说明这些值的意义，或者你可以使用常量使代码自文档化。比较以下两段代码：,bool success = CalculateSomething(interesting_value,10,false,NULL);/,这些参数都是什么意思？,VS,bool success = CalculateSomething(interesting_value,10, /,默认基数,flase,/,非第一次调用,NULL);/,无回调,也可以使用替代方案，常量或自描述的变量：,const int kDefaultBaseValue = 10;,const bool kFirstTimeCalling = false;,callback *null_callback = NULL;,bool success = CalculateSomething(interesting_value,kDefaultBaseValue,kFirstTimeCalling,null_callback);,不要这么做：,不要试图描述代码本身。假设代码阅读者比你更了解,C+,，既使这样，他,/,她也对你到底想做什么毫无头绪。,/,现在遍历,b,数组并且确保如果,i,存在，下一个元素是,i+1,。,./,天哪，这些都是垃圾注释,函数声明和定义、函数调用、条件语句、循环语句和类的格式规范,函数声明与定义,(Function Declarations and Definitions),返回类型和函数名在同一行，如果空间足够，参数列表也应在同一行。即：,ReturnType ClassName:FunctionName(Type par_name1,Type par_name2),DoSomething();,.,如果一行输入不完，可以分成多行：,ReturnType ClassName:ReallyLongFunctionName(Type par_name1,Type par_name2,Type par_name3),DoSomething();,.,也可以每个参数各占一行：,ReturnType LongClassName:ReallyRealyReallyLongFunctionName(,Type par_name1, / 4,个空格的缩进,Type par_nane2,Type par_name3),DoSomething();,需要注意的地方,：,返回类型应该保持与函数名在同一行；,左括号应该与函数名保持在同一行且中间不应该有空格；,括号与参数之间不应该有空格；,左花括号应该与最后一个参数保持在同一行；,右花括号要么独自一行，要么与左花括号保持在同一行（其他风格规则允许时）；,右圆括号与左花括号之间应该有一个空格隔开；,无论是函数声明还是函数实现，都应该给参数命以同样的名称；,默认缩进,2,个空格；,分行的参数以,4,个空格缩进；,定义,const,函数时，,const,关键字应该与最后一个参数保持在同一行。,/,这个函数签名中的所有代码不超过,80,个字符,ReturnType FunctionName(Type par) const,.,/,这个函数签名需要分行，但注意，,const,与最后一个参数保持在同一行,ReturnType ReallyLongFunctionName(Type par1,Type par2)const,.,如果有未使用参数，在函数实现中注释其名称：,/,在接口中，参数一定要命名,class Shape,public:,virtual void Rotate(double radians) = 0;,;,/,在声明中，参数一定要命名,class Circle : public Shape,virtual void Rotate(double radians);,;,/,在函数实现中，以注释注明未使用的参数命名,void Circle:Rotate(double /*radians*/),/,不好如果以后需要其他人实现，参数名称不详,void Circle:Rotate(double),函数调用,(Function Calls),尽量书写在一行，如果字符太多，将参数分行。比如：,bool retval = DoSomething(argument1,argument2,argumetn3);,如果参数无法在同一行内写完，可以分行，每一行的参数都应该与第一个参数对齐，且不要在左圆括号后或右圆括号前加空格。,bool retval = DoSomething(averyveryveryverylongargument1,argument2,argument3);,如果函数参数太多，可以每一行写一个参数，这样代码更可读：,bool retval = DoSomething(argument1,argument2,argument3,argument4);,如果参数签名太长，超过最大,行宽,，可以将参数分行写书：,if(.),.,.,if(.),DoSomethingTheatRequiresALongFunctionName(,very_long_argument1, /,缩进,4,个空格,argument2,argument3,argument4);,条件语句,(Conditonals),括号内最好不要有空格，,else,应该另起一行。,基本条件语句主要有两种常见格式：一种是在括号和条件中插入空格，另一种是没有。但后者更常用。尽管两种方式都可以，但注意保持一致性。当你修改别人的代码时，保持与已有风格的一致；而当你添加新代码时，与当前目录或项目中已有代码的风格保持一致。当你不确定而且感觉无所谓时，不要插入空格。,if(condition) /,括号内没有空格,. /,缩进,2,个空格,else / else,与右花括号在同一行,.,当然，你也可以根据自己的喜好在括号内插入空格,if ( condition ) /,括号内插入空格不常用,. /,缩进,2,个空格,else / else,与右花括号在同一行,.,注意：,if,和左圆括号之间应该有空格。右圆括号和左花括号（如果使用）之间也应该有空格。,if(condition) /,糟糕,IF,后面没有空格,if (condition) /,糟糕右圆括号和左花括号之间没有空格,if(condition) /,非常糟糕,为便于阅读，简短的条件语句可以写在同一行。但仅限于这行代码很明确且没有,else,分支的情况：,if (x = kFoo) return new Foo();,if (x = kBar) return new Bar();,/ if,语句有,else,分支，不允许写在同一行,if (x) DoThis();,else DoThat();,通常，单语句条件语句不需要花括号，但可以根据自己的喜好加上。有复杂条件和语句的条件和循环加上圆括号后更具可读性。一些项目甚至要求,if,在所有情况都应该加上花括号。,if ( condition ),DoSomething(); /,缩进,2,个空格,if (condition) ,DoSomethign();,为保持一致，,if,或者,else,分支加了花括号，另一分支也应该加上。,/,不允许,if,分支有花括号，而,else,分支没有,if (condition) ,foo;,else,Bar;,/,不允许,else,分支有花括号，而,if,分支没有,If (condition),foo;,else ,bar;,/ if,和,else,分支都应该加上花括号，因为它们之一有,if (condition) ,foo;,else,Bar;,循环和多分支语句,(Loops and Switch Statements),在多分支语句中，块可以用花括号限制。而对于无循环体的循环，可以使用,或,continue,。,case,语句块可根据自己的喜好使用花括号，如果使用花括号，请遵照下面的格式：,除非是判断枚举类型，多分支语句应该有一个默认分支（在枚举情况下，编译器将检测到未处理分支并警告）。如果默认分支不可能被执行，使用断言,(assert),声明。,swtich (var) ,case 0: ,.,Break;,case 1: ,.,Break;,default: ,assert(false);,空循环体应该用,或者,continue,，但不要用单独的分号：,while (condition) ,/,一直测试条件，直到它返回假,for(int i = 0; i kSomeNumber;+i) /,很好空循环体,while (condtiton) continue; /,很好,continue,指示无逻辑,while (condition); /,糟糕看起来像是,do/while,循环,类格式,(Class Format),成员按,public,、,protected,和,private,的次序定义，每个部分缩进,1,个空格。下例显示了基本的类格式（例子中缺少必要的注释，参见类注释,(Class Comments),部分）：,class MyClass : public OtherClass,public: /,注意，缩进,1,个空格,MyClass(); /,注意，缩进,2,个空格,Explicit MyClass(int var);,MyClass(),void SomeFunction();,void SomeFunctionThatDoesNothing(),void set_some_var(int var) some_var = var; ,int some_var() const reurn some_var; ,private:,bool SomeInternalFunction();,int some_var;,int some_other_var;,DISALLOW_COPY_AND_ASSIGN(MyClass);,注意：,基类名称直接置于子类名称后的同一行内而不受最大长度（,80,字符）的限制；,public:protected:,和,private:,只需缩进,1,个空格，且除非是第,1,个实例的情况，它们应该位于单独的行，最好在紧接着的下一行进行成员声明；,public,部分行,1,位、,protected,部分第,2,位，,private,放在最后；,谢谢,