根据项目使用的许可(例如, Apache 2.0, BSD, LGPL, GPL), 选择合适的样板.
3.8.3函数和方法
下文所指的函数,包括函数, 方法, 以及生成器....一个函数必须要有文档字符串, 除非它满足以下条件:
(1)外部不可见
(2)非常短小
(3)简单明了
文档字符串应该包含函数做什么,以及输入和输出的详细描述.通常,不描述"怎么做",除非是一些复杂的算法...由于字符串是不可变的,这将创建不必要的临时对象,并导致二次而不是线性的运行时间。...运用判断力在一方面的安全性和清晰度与另一方面的灵活性之间取得良好的平衡。
注释易于发生类型相关错误(先前的错误或复杂性)的代码。
注释难以理解的代码。...在许多情况下,您可以在成熟的代码中注释所有功能,而不会失去太多的灵活性。
3.19.2换行
注释后,许多功能签名将变成“每行一个参数”。