律师行业网站模板/seo工作流程
点击上方蓝字设为星标
每周一、三、五上午 8:30 准时推送
下面开始今天的学习～
良好的注释
你可能听说过「好的代码本身就是注释」这句话，它是否正确？它正确。这是否意味着你不需要写注释？不是。注释对代码的可读性至关重要，虽然写注释很痛苦，但为了将来方便，程序员仍需花费时间写注释。
当然，不能因为拥有注释就放弃对代码本身质量的追求。在《Clean Code》一书中，作者着重强调「注释不能美化糟糕的代码」，使用有意义的类型名或变量名可能比注释更加直观易懂。
文件注释
文件注释一般包含版权声明和对文件内容的大致说明。这类声明/说明要尽量简短，对版权内容而言，能使用外部链接就不要将法律条款放到注释中；对文件内容而言，只需用一到两行说明各概念之间的联系。
类和函数的注释
类在定义时应当附带注释，用于描述其功能和用法，除非其功能和用法十分明显。
函数在定义时应当包含注释，除非该函数非常短小或者简单明了。(对于 Python 而言，如果该函数外部不可见，那么不需要使用文档字符串)注释中应当描述该做什么、输入和输出，一般我们不描述「怎么做」，除非算法本身非常复杂。以下是一个 Python 的注释示例(来自 Google 开源项目风格指南)：
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): """Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. Raises: IOError: An error occurred accessing the bigtable.Table object. """ passArgs:
列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行 80 字符,使用 2 或者 4 个空格的悬挂缩进(与文件其他部分保持一致)。 描述应该包括所需的类型和含义。 如果一个函数接受 foo(可变长度参数列表)或者 **bar (任意关键字参数), 应该详细列出 foo 和 **bar.
Returns: (或者 Yields: 用于生成器)
描述返回值的类型和语义. 如果函数返回 None, 这一部分可以省略。
Raises:
列出与接口有关的所有异常。
行注释
将注释放置在想要注释的代码之上一行，而不要挤在一行中。在注释和上一行代码之间添加一个空行，除非这个注释在一个代码片段的最顶部。下例来自 Airbnb JavaScript 编程规范。
// badconst active = true; // is current tab// good// is current tabconst active = true;// badfunction getType() { console.log('fetching type...'); // set the default type to 'no type' const type = this.type || 'no type'; return type;}// goodfunction getType() { console.log('fetching type...'); // set the default type to 'no type' const type = this.type || 'no type'; return type;}// also goodfunction getType() { // set the default type to 'no type' const type = this.type || 'no type'; return type;}对于空行的问题，不同的风格指南会给出不同的引导，如 Google 开源项目风格指南 Python 篇章中，规定注释应该至少离开代码 2 个空格，但允许写在一行之中。无论如何，只要保证注释和代码有明显的区分度即可。
在注释符号和注释内容之间添加空格以便于阅读。
// bad//is current tabconst active = true;// good// is current tabconst active = true;TODO 注释和 FIXME 注释
使用 FIXME 注释标注问题，使用 TODO 注释标注解决方案。
警示
有时我们可以用注释警告其他程序员要或不要做某事。比如，在某些关键的测试用例上警告其他程序员不要关闭它。
良好的代码格式
命名
《Clean Code》一书中对良好命名做出了详细的描述，本文对该书第二章和第五章做出部分总结：
名副其实：不要使用没有意义的变量名，也不要让变量名和变量本身表达的含义不符
避免误导：比如如果数据类型不是 List，就不要在变量名中使用 List 这个词
类名应当是名词或名词短语；方法名应当是动词或动词短语
源文件的名称应当简洁，并且能通过名字告诉我们它是否在正确的模块中
函数
时刻注意将细节抽象成函数
一个函数应该只做一件事
源文件顶部应当给出最高层次的概念或函数，逐渐向下展开，在文件的最底部，应当放着最底层的细节
关系密切的函数应该靠得更近
使用描述性的函数名，长而具有描述性的名称优于短小而费解的名称
函数要尽可能没有副作用
函数要尽可能不重复
空格和空行
代码的每一行展现一个目的
一组代码展示一段完整的思路
不同的思路中间用空行隔开
尽可能避免一行结尾的空格，这种空格很难被发现，但可能会引起问题
良好的文档
通过使用工具，我们可以通过编写良好注释让工具为我们自动生成函数文档，下面是两个常用工具：
Doxygen 可以通过识别源代码生成代码文档。目前它支持 C、 Objective-C、C#、PHP、Java、Python 等等编程语言。
Sphinx 是一个类似的项目，最初其为新版的 Python 创建，现在也支持 C/C++。
以上两个工具你可以选择生成 HTML、PDF、LaTeX 等等格式。
参考资料
PEP 8 -- Style Guide for Python Code: https://www.python.org/dev/peps/pep-0008/
Google 开源项目风格指南: https://zh-google-styleguide.readthedocs.io/en/latest/contents/
《Clean Code》 - Robert C. Martin
《Eloquent JavaScript》: https://eloquentjavascript.net/
Airbnb JavaScript Style Guide:https://github.com/airbnb/javascript
本文作者：宫业奇
编辑&版式：霍霍
声明：本文归 “力扣” 版权所有，如需转载请联系。
