本文档大概指出了部分语言的相关注释的注意事项,主要涵盖JavaScript、Java、C++、Python等公司中大量使用的语言
注释的好处
佛系讲解代码注释的好处(转载请指明出于breaksoftware的csdn博客)
部分注释
文件注释写入文件头部
"""
filename:[文件名]
author:〈版权〉
describe:〈描述〉
修改人:〈修改人〉
修改时间:YYYY-MM-DD
修改内容:〈修改内容〉
"""
二次开发注释
filename:[文件名]
author:〈版权〉
describe:〈描述〉
modifier:〈修改人〉
modificationTime:YYYY-MM-DD
modificationContent:〈修改内容〉
文件注释
需要添加的内容包括:
- 版权信息
- 文件内容
- 作者信息
涉及复杂模块,需要添加一个例如 doc.go、README.md 等相关文件,里面主要描述模块的问题背景、实现的功能、设计的思路、参考链接、非功能性的考虑等。
类注释
需要添加的内容包括:
- 类的功能
- 类的使用方法(如果可以,可以写一些使用例子)
- 注意事项或者说明(如不支持并发等)
函数注释
需要添加的内容包括:
- 函数功能
- 函数的输入输出
- 注意事项说明(如有性能问题、是否可重入等)