作者ripple0129 (perry tsai)
看板Soft_Job
标题Re: [请益] 写注解到底是不是好习惯
时间Thu Dec 27 23:50:54 2018
这种讨论clean code的东西
各有各的说词
我个人也是偏向不注解
但可能注解说明该module功能
或是注解回传的资料结构
譬如
def get_city_population():
"""
return ［
{Taipei:[
{NanGan:1000},{WanHua:1000}...］
]
...
]
"""
手机排版随便排的看不懂请见谅
让使用方法的人快速了解嵌套结构
当然这也有code与注解版本不相符的问题
不过个人觉得这会算是帮助快速理解
蛮实用的注解方式
而太基本的方法千万不要多写
特别是强型别的语言更别加废话注解
public int getAge(User user)
这种注解取得user年龄的废话
就是为了注解而注解了
程式码能够完整表达意图时
只需要思考意图之外
还需要告诉读code的人的事
才需要额外说明
譬如
#Boss required to do this, you have to suck it
有时候去看一些大型专案的开源原始码
注解比code还多啊XD
而且一些是在讲继承与依赖关系
个人觉得不是那麽必要
真正需要去搞懂原始码的时候
通常自己靠源码分析工具
来了解相依性的部分
还有图可以看呢
总结来说注解的重点就是
能够帮助读者快速理解
以及程式码之外的告知事项
其他就没有必要
而注解的事项尽量会是不因为code的改动
而需要去修改的这类型注解
更新code忘记更新注解
每个人都一定有过这种经验嘛
--
※ 发信站: 批踢踢实业坊(ptt.cc), 来自: 1.171.204.87
※ 文章网址: https://webptt.com/cn.aspx?n=bbs/Soft_Job/M.1545925856.A.7C1.html
1F：→ testPtt: 我是会做相依性注解 程式改这种注解难免要改12/28 00:17
2F：推 piadora: 请问有什麽工具可以帮助画图12/28 00:40
譬如说
VS的Code maps
PHP RIPS
※ 编辑: ripple0129 (1.171.204.87), 12/28/2018 01:06:36
3F：推 BoXeX: 我是觉得跟开发环境和团队状况有关 12/28 01:13
4F：→ BoXeX: 当整个团队能用的工具越少 就越需要注解来帮忙 12/28 01:14
5F：→ BoXeX: 还有如果要给其他团队看的 多一点注解可以帮助理解 12/28 01:15
6F：→ BoXeX: 同team的人习惯接近了 觉得clean到不行 12/28 01:16
7F：→ BoXeX: 换个团队看就变成无字天书 12/28 01:16
8F：推 h124224: 还要考虑其他team也太累了吧 如果不是经常要看 为了其他 12/28 04:59
9F：→ h124224: team写注解只是浪费时间而已 12/28 04:59
10F：→ h124224: 应该说，经常有人要第一次看 12/28 05:00
11F：→ dnabossking: 当注解一堆的时後，他妈就是代表你的code有问题啦， 12/28 09:15
12F：→ dnabossking: 不想着怎麽把code写的更简洁，只想用注解来逃避自己 12/28 09:15
13F：→ dnabossking: 的烂code真的是超烂的 12/28 09:15
14F：→ dnabossking: 不是写注解不好，而是别写一堆废注解，还自以爲是在 12/28 09:19
15F：→ dnabossking: 提声可读性 12/28 09:19
16F：推 t64141: 遇过楼上说的这种，程式一团乱，然後跟我说看他写的注解就 12/28 09:23
17F：→ t64141: 知道功能了 12/28 09:23
18F：推 jack0204: swagger之类的就是要写注解才有用阿 12/28 09:28
19F：→ jack0204: PHP很多IDE都是靠注解来判断函式的，怎麽可能不写 12/28 09:28
20F：→ knives: 可是我认为swagger那种PHP Doc 的不是大家讨论的那种注解 12/28 09:30
21F：→ rofellosx: 习惯用建新的code取代修改就没忘记更新注解问题 即使与 12/28 09:39
22F：→ rofellosx: 旧的有87%像.. 12/28 09:39
23F：嘘 deray: 靠北咧 Phpdoc跟注解不一样好吗 12/28 10:03
24F：推 jack0204: 它不是注解难道是程式码吗? 它也是注解的一种阿 12/28 10:17
25F：→ jack0204: 注解的定义本来就很大，问题是写到什麽程度而已 12/28 10:19
26F：→ testPtt: 打在code里跟程式功能无关的可以当做注解 12/28 10:36
27F：→ testPtt: 甚至c# attribute 也可以算注解 12/28 10:37
28F：→ BoXeX: 所以我才说要看团队状况 12/28 11:39
29F：→ BoXeX: 一个专案少说几万行 你不加注解同team的还是觉得很好懂 12/28 11:41
30F：→ BoXeX: 但其他人一但要碰 根本无从下手 12/28 11:42
31F：→ BoXeX: 更多的是自以为 clean code 不写注解 结果超 dirty 12/28 11:45
32F：→ BoXeX: 另外要求新手不加注解的我也不太能体会 12/28 11:47
33F：→ testPtt: 几万行过几个月回来看就不懂了 就算都自己写的也一样 12/28 11:53
34F：→ deray: Document 跟 Comment 都分不清的话 还有讨论的必要吗？ 12/28 12:10