大家注释怎么写的

2016-06-12 12:51:55 +08:00
 brucefeng

最近团队开始有新人进入，在写代码注释上，有一些不同点。之前团队提倡的是尽量少写注释，让代码有自说明的作用，如果实在无法通过代码表达，再在接口 /方法级别写注释，其他地方不再多加注释了。

新人的注释习惯比较多，有的系统对关键代码行写步骤注释，有些接口和实现都有注释，有时候注释太多，感觉影响代码。

问问大家都是怎么写的。

8393 次点击
所在节点    Java
64 条回复
franklinyu
2016-06-20 16:11:11 +08:00
我認爲基本不應該有註釋，但是應該有文檔。 Javadoc 就挺夠用的，集成開發環境也廣泛支持 Javadoc 。
franklinyu
2016-06-20 17:01:05 +08:00
我的想法跟 @lightening 差不多：公有函數，文檔一定要寫夠；私有函數，按照名字的直觀性判斷是否寫文檔，沒辦法用函數名和參數名來自行解釋的，就寫上文檔；文檔裏面不寫怎麼實現的（ how ），只寫實現了什麼（ what ），調用了以後會發生什麼；至於怎麼實現的，用了哪些技巧，碰了哪些釘子，都寫到 commit message 裏面，當作筆記來用。
8023
2016-06-23 13:35:28 +08:00
@franklinyu 学习到了, 多谢.
ihuotui
2016-08-19 04:55:10 +08:00
业务接口可以注释，其他函数如果需要注释证明复杂度太高了

这是一个专为移动设备优化的页面（即为了让你能够在 Google 搜索结果里秒开这个页面），如果你希望参与 V2EX 社区的讨论，你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://ex.noerr.eu.org/t/285087

V2EX 是创意工作者们的社区，是一个分享自己正在做的有趣事物、交流想法，可以遇见新朋友甚至新机会的地方。

V2EX is a community of developers, designers and creative people.

© 2021 V2EX