源程序文档化.ppt

软件工程研讨源程序文档化 第六组组员 12122208陈帅12123298马敏12123249雷晴12123256邱可艺 2014 12 16 变量 常量和函数的命名规范 变量名所有字母小写 单词之间用下划线 分开 类成员变量以下划线结束 普通变量命名 CommonVariableNames 比如 类数据组成变量命名 ClassDataMembers 数据成员 又叫实例变量或者成员变量 的命名与普通变量一样 全部字母小写 可选的下划线分隔符 但应该以下划线结束 stringtable name 可以 以下划线结束stringtablename 可以 变量命名 VariableNames stringtable name 可以 使用下划线stringtablename 可以 全部字母小写stringtableName 糟糕 大小写混合 结构体成员变量命名 StructVariables 结构体成员变量和普通变量命名规则一致 且不像类成员变量以下划线结束 structUrlTableProperties stringname intnum entries 全局变量命名 GlobalVariables 全局变量的使用较为罕见 但当用到时 考虑以前缀g 开头或标以其他记号 以便与局部变量区分 常量命名 ConstantNames K后跟混合大小写的名称 kDaysInAWeek 所有编译时常量 不管是被声明为局部 全局还是作为类的成员 都应该遵守与其他变量命名有轻微差别的命名约定 k后跟单词首字母大写的名称 constintkDaysInAWeek 7 函数命名 FunctionNames 正规函数名应该以大写字母开头 单词首字母大写 不使用下划线 如果函数可能因错误而崩溃 应该在函数名后加上OrDie 这仅适用于那些被产品代码调用或者正常操作有可能引起错误的函数 AddTableEntry DeleteUrl OpenFileOrDie 访问器和修改器 AccessorsandMutators 访问器和修改器 get和set函数 应该与它们关联的变量名匹配 下面显示了一个类的部分摘录 它有一个实例变量num entries classMyClass public intnum entries const returnnum entries voidset num entries intnum entries num entries num entries private intnum entries 你也可以使用小写字母和下划线来命名非常短小的内联函数 比如 如果一个函数的调用开销很小 在循环调用时 没必要缓存其值 这时 小写字母命名是允许的 对文件 类 函数 变量和逻辑功能段进行注释的规范 文件注释 FileComments 每个文件都应该提供版权信息 然后是文件内容的综合性描述 合法公告和作者信息行 LegalNoticeandAuthorLine 每个文件都应依次包括以下条目 1 版权声明 比如Copyright2008GoogleInc 2 一个许可引用 选择适合你项目使用的许可引用 比如Apache2 0 BSD LGPL GPL 3 作者信息行说明文件原始作者 如果你对原始作者的文件做了实质性修改 可以在作者信息行加上你的名字 当其他开发者有问题时 这样可以方便他们正确地联系到修改者 文件内容注释 FileContents 每个文件都应该在其版权信息及作者信息后面和内容前面有一个内容描述性的注释 通常 头文件描述它所声明的类的目的及用法 而源文件则应该包含更多有关实现和技巧性算法的讨论信息 但如果你觉得这些信息对于头文件的阅读者更有用 可以将其放在头文件中 但在源文件中应该注明其文档在头文件中 不要在头文件和源文件中重复注释 这样容易造成歧义 类注释 ClassComments 每个类定义都应该伴随有说明其目的和用法的注释 遍历GargantuanTable的内容 用法示例 GargantuanTableIterator iter table NewIterator for iter seek foo iter done iter next process iter key iter value deleteiter ClassGargantuanTableIterator 如果你在文件开始就已对类进行了详细描述 可以在类实现部分简单地声明 参见文件开始注释部分的完整描述 但注意 这里还是要添加少量注释 函数注释 FunctionComments 函数声明部分的注释描述函数的用法 实现部分的注释描述函数实现的操作 每个函数声明的前面都应该有一个描述函数功能和用法的注释 这些注释应该是描述性 Opensthefile 而不是祈使性的 Openthefile 注释仅仅描述函数能够完成什么功能而不是函数是怎么实现的 这些应该在函数实现的注释中 在函数声明注释中应该提到的信息类型 1 输入和输出 2 对于类成员函数 在该方法的调用周期外 对象是否有引用参数 它是否会释放这些引用 3 如果一个函数申请了内存 它必须释放它们 4 参数是否可以是空 5 函数的使用方法是否会影响其性能 6 如果函数可重入 它是怎么实现同步的 例子 返回这个表的一个迭代器 当遍历结束时 由客户程序负责迭代器的释放 一旦此迭代器的创建者GargantuanTable对象被释放 客户程序不可再使用此迭代器 迭代器被初始化为指向表的开始 这个方法等价于 Iterator iter table NewIterator iter seek returniter 如果你想立即寻找返回的迭代器中的另一个位置 使用NewIterator 更快 而 且避免了额外的查找 Iterator getIterator const 然而 避免不必要的冗长注释且不要添加显而易见的注释 比如下例外中 返回假的情况就没必要 因为这很明显 如果表已被占满 不能再容纳实体 则返回真boolIsTableFull 当给构造和析构函数加注释时 注意 读者清楚地知道这些函数的作用 所以诸如 销毁这个对象 的注释毫无意义 注释内容应该说明构造函数怎样处理参数 比如它是否取得指针的控制权 和析构函数怎么完成清理工作 如果这些不很重要 可以省略它们 文件的开头注释中没有关于析构函数的注释是很正常的 函数定义注释 FunctionDefinition 每个函数都应该有一个注释来描述函数的功能和其完成这些功能的实现技巧 如果有的话 比如 你在函数定义注释中 你可以描述编码中用到的技巧 给出大致的执行步骤或者解释一下你选择这种实现而不使用其他替代方法的原因 比如 你可能需要说明为什么函数前半部分需要锁而后半部分不需要 注意 不能简单地重复头文件或者其他地方函数声明部分的注释 可以再次概括一下函数的功能 但焦点应该是函数是怎么实现功能的 变量注释 VariableComments 通常 一个变量的实际名称已经提供了足够和描述信息来说明其用途 但某些情况下 可能需要更多注释 类数据成员 ClassDataMembers 每个类数据成员 也称实例变量或者成员变量 应该有一个描述其用途的注释 如果这个变量能取得具有特殊意义的标志值 比如NULL或 1 则需要加以说明 比如 Private 记录表中实体的总数 用于确保不打破数量限制 1意味着表的实体数未知intnum total entries 全局变量 GlobalVariables 和数据成员一样 所有全局变量应该有一个描述其功能及其意义的注释 比如 所有本次回归测试使用到的测试用例数cosntintkNumTestCases 6 实现注释 ImplementationComments 在实现中 应该对你代码技巧性的 不明显的 有趣的或者重要的部分进行注释 类数据成员 ClassDataMembers 技巧性的和复杂难懂的代码块前应该有注释 Divideresultbytwo takingintoaccountthatx containsthecarryfromtheaddfor inti 0 isize i x x 1 X 行注释 LineComments 同样 当行代码中有不明显的地方时 也需要在其行末添加注释 这种行末注释应该以2个空白与代码分开 Ifwehaveenoughmoney mmapthedataportiontoo mmap budget max 0 mmap budget index length if mmap budget data size Erroralreadylogged 可以看到 这里即有描述代码功能的注释 也有提醒函数返回时错误已经被记录的注释 如果有多行注释 将它们整齐排列将增加可读性 DoSomething CommentheresothecommentslineupDoSomethingElseThatIsLong Commentheresotherearetwospaces betweenthecodeandthecomment Onespacebeforecommnetwhenopeninganewscopeisallowed thusthecommentlinesupwiththefollowingcommentsandcodeDoSomethingElse Twospacesbeforelinecommentsnormally 逻辑功能段进行注释 当给函数传入NULL 布尔值和整型值串时 应该增加注释以说明这些值的意义 或者你可以使用常量使代码自文档化 比较以下两段代码 boolsuccess CalculateSomething interesting value 10 false NULL 这些参数都是什么意思 VS boolsuccess CalculateSomething interesting value 10 默认基数flase 非第一次调用NULL 无回调 也可以使用替代方案 常量或自描述的变量 constintkDefaultBaseValue 10 constboolkFirstTimeCalling false callback null callback NULL boolsuccess CalculateSomething interesting value kDefaultBaseValue kFirstTimeCalling null callback 不要这么做 不要试图描述代码本身 假设代码阅读者比你更了解C 既使这样 他 她也对你到底想做什么毫无头绪 现在遍历b数组并且确保如果i存在 下一个元素是i 1 天哪 这些都是垃圾注释 函数声明和定义 函数调用 条件语句 循环语句和类的格式规范 函数声明与定义 FunctionDeclarationsandDefinitions 返回类型和函数名在同一行 如果空间足够 参数列表也应在同一行 即 ReturnTypeClassName FunctionName Typepar name1 Typepar name2 DoSomething 如果一行输入不完 可以分成多行 ReturnTypeClassName ReallyLongFunctionName Typepar name1 Typepar name2 Typepar name3 DoSomething 也可以每个参数各占一行 ReturnTypeLongClassName ReallyRealyReallyLongFunctionName Typepar name1 4个空格的缩进Typepar nane2 Typepar name3 DoSomething 需要注意的地方 返回类型应该保持与函数名在同一行 左括号应该与函数名保持在同一行且中间不应该有空格 括号与参数之间不应该有空格 左花括号应该与最后一个参数保持在同一行 右花括号要么独自一行 要么与左花括号保持在同一行 其他风格规则允许时 右圆括号与左花括号之间应该有一个空格隔开 无论是函数声明还是函数实现 都应该给参数命以同样的名称 默认缩进2个空格 分行的参数以4个空格缩进 定义const函数时 const关键字应该与最后一个参数保持在同一行 这个函数签名中的所有代码不超过80个字符ReturnTypeFunctionName Typepar const 这个函数签名需要分行 但注意 const与最后一个参数保持在同一行ReturnTypeReallyLongFunctionName Typepar1 Typepar2 const 如果有未使用参数 在函数实现中注释其名称 在接口中 参数一定要命名classShape public virtualvoidRotate doubleradians 0 在声明中 参数一定要命名classCircle publicShape virtualvoidRotate doubleradians 在函数实现中 以注释注明未使用的参数命名voidCircle Rotate double radians 不好 如果以后需要其他人实现 参数名称不详voidCircle Rotate double 函数调用 FunctionCalls 尽量书写在一行 如果字符太多 将参数分行 比如 boolretval DoSomething argument1 argument2 argumetn3 如果参数无法在同一行内写完 可以分行 每一行的参数都应该与第一个参数对齐 且不要在左圆括号后或右圆括号前加空格 boolretval DoSomething averyveryveryverylongargument1 argument2 argument3 如果函数参数太多 可以每一行写一个参数 这样代码更可读 boolretval 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 returnnewFoo if x kBar returnnewBar if语句有else分支 不允许写在同一行if x DoThis elseDoThat 通常 单语句条件语句不需要花括号 但可以根据自己的喜好加上 有复杂条件和语句的条件和循环加上圆括号后更具可读性 一些项目甚至要求if在所有情况都应该加上花括号 if condition DoSomething 缩进2个空格if condition DoSomethign 为保持一致 if或者else分支加了花括号 另一分支也应该加上 不允许 if分支有花括号 而else分支没有if condition foo elseBar 不允许 else分支有花括号 而if分支没有If condition foo else bar if和else分支都应该加上花括号 因为它们之一有if condition foo else Bar 循环和多分支语句 LoopsandSwitchStatements 在多分支语句中 块可以用花括号限制 而对于无循环体的循环 可以使用 或continue case语句块可根据自己的喜好使用花括号 如果使用花括号 请遵照下面的格式 除非是判断枚举类型 多分支语句应该有一个默认分支 在枚举情况下 编译器将检测到未处理分支并警告 如果默认分支不可能被执行 使用断言 assert 声明 swtich var ca