假如党委给你两个工程项目的源标识符让你写作，并认知解构标识符，但里头句注解都没，我想这的确是以后同僚“删库跑路”了。
看这份源标识符甚么很关键？除各式各样标识符规范化以外，除了两个较为关键的是注解。注解尽管写出来很痛苦, 但对确保标识符时效性非常关键，上面的将叙述怎样注解和在哪里注解。
注解艺术风格
1
概要
通常采用 // 或 /* */，如果标准化就好。
2
表明
// 或 /* */ 都能，但 // 更 常见，要在怎样注解及注解艺术风格上确保标准化。
文档注解
1
概要
在每两个文档结尾重新加入著作权、译者、天数等叙述。
文档注解叙述了该文档的文本，假如两个文档只新闻稿，或同时实现，或试验了两个第一类，因此那个第一类早已在它的新闻稿处展开了详尽的注解，那么就没必要性再加之文档注解，除此以外的其它文档都须要文档注解。
2
表明
法律公告和译者信息：
每个文档都应该包含许可证引用. 为工程项目选择合适的许可证版本(比如, Apache 2.0, BSD, LGPL, GPL)。
假如你对原始译者的文档做了重大修改，请考虑删除原译者信息。
3
文档文本
假如两个 .h 文档新闻稿了多个概念, 则文档注解应当对文档的文本做两个大致的表明, 同时表明各概念之间的联系. 两个一到两行的文档注解就足够了, 对于每个概念的详尽文档应当放在各个概念中, 而不是文档注解中。不要在 .h 和 .cc 之间复制注解, 这样的注解偏离了注解的实际意义。
函数注解
1
概要
函数新闻稿处的注解叙述函数功能; 定义处的注解叙述函数同时实现。
2
表明
函数新闻稿：
基本上每个函数新闻稿处前都应当加之注解, 叙述函数的功能和用途. 只有在函数的功能简单而明显时才能省略这些注解（如简单的取值和设值函数）。
比如：FreeRTOS创建任务函数申明：
函数定义：
假如函数的同时实现过程中用到了很巧妙的方式, 所以在函数定义处应当加之解释性的注解。比如, 你所采用的编程技巧, 同时实现的大致步骤, 或解释如此同时实现的理由. 举个例子, 你能表明为甚么函数的前半部分要加锁而后半部分不须要。不要 从 .h 文档或其它地方的函数新闻稿处直接复制注解. 简要重述函数功能是能的, 但注解重点要放在怎样同时实现上。
变量注解
1
概要
通常变量名本身足以很好表明变量用途， 某些情况下, 也须要额外的注解表明。
2
表明
根据不同场景、不同修饰符，变量能分为很多种类，总的来说变量分为全局变量、局部变量。
通常来说，局部变量仅限于局部范围，其含义相对简单容易认知，只须要简单注解即可。
全局变量通常作用于多个文档，或者整个工程，因此，其含义相对更复杂，所以在注解的时候，最好叙述清楚其具体含义，是尽量全面叙述。
（提示：全局变量尽量少用）
拼音注解
1
概要
可能将两个变量、两个函数包含的意思非常复杂，须要多个单词拼写而成，此时对拼写文本就须要详尽注解。
2
表明
注解的通常写法是包含正确大小写和结尾句号的完整叙述性语句. 大多数情况下, 完整的句子比句子片段时效性更高. 短一点的注解, 比如标识符行尾注解, 能随意点, 但依然要注意艺术风格的一致性。
同时，注解中的拼写、逗号也很关键。尽管被别人指出该用分号时却用了逗号多少有些尴尬, 但清晰易读的标识符还是很关键的. 正确的标点, 拼写和语法对此会有很大帮助。
TODO注解
1
概要
对那些临时的, 短期的解决方案, 或早已够好但仍不完美的标识符采用 TODO 注解。
TODO 注解要采用全大写的字符串 TODO , 在随后的圆括号里写上你的名字, 邮件地址, bug ID, 或其它身份标识和与这一 TODO 相关的 issue. 主要目的是让添加注解的人 (也是能请求提供更多细节的人) 可根据规范化的 TODO 格式展开查找. 添加 TODO 注解并不意味着你要自己来修正, 因此当你加之带有姓名的 TODO 时, 通常都是写上自己的名字。
最后
注解固然很关键, 但最好的标识符应当本身是文档，有意义的类型名和变量名, 要远胜过要用注解解释的含糊不清的名字。
你写的注解是给标识符写译者看的, 也是下两个须要认知你标识符的人。所以慷慨些吧, 下两个读者可能将是你！
