注释写得太多了会挨打吗？

注释

挨打

写

吗

145 条回复 • 2018-09-27 18:27:25 +08:00

1 2

❮

❯

1

whypool

2018-09-25 17:33:54 +08:00

会，把注释当文档了

2

pain400

2018-09-25 17:34:17 +08:00

挺好的

3

orange1818

2018-09-25 17:36:10 +08:00

我已经备好手枪了

4

easylee

2018-09-25 17:37:56 +08:00 via Android

一份经久不衰的代码，注释量与代码量的比应该至少为 2:1。

5

fundebug

OP

2018-09-25 17:39:01 +08:00

1

@orange1818 《刑法》第一百二十八条第一款的罪名为非法持有、私藏枪支、弹药罪。该款规定：违反枪支管理规定，非法持有、私藏枪支、弹药的，处三年以下有期徒刑、拘役或者管制；情节严重的，处三年以上七年以下有期徒刑。

6

smilepig

2018-09-25 17:39:05 +08:00

详细点是蛮好的。。。

7

wupher

2018-09-25 17:40:04 +08:00

7

别的都还好，console.warn 我笑了

8

Mariano

2018-09-25 17:40:11 +08:00

随便看了一眼，密密麻麻的字看的我头疼

9

yulitian888

2018-09-25 17:41:54 +08:00

2

不写注释才会被打呢
比如下面这样的：

/*

+---------------+
| |
| 本数据库操作类 |
| |
+--+--+---------+
| ^
v |
|
+-----+---------+
| |
| 数据库 |
| |
| |
+---------------+

*/

10

ranoff

2018-09-25 17:45:49 +08:00

个人觉得的有点多

11

zhangjiabin1010

2018-09-25 17:46:40 +08:00

喜闻乐见啊，多写点注释，方便你我他

12

yangxiongguo

2018-09-25 17:48:04 +08:00

导出一下就是文档了啊

13

kios

2018-09-25 17:48:15 +08:00

写多了我不知道，写少了可能会被同事强杀

14

keinx

2018-09-25 17:48:47 +08:00

9

有个同事写的注释特别有意思，注释里面带了很多段子，有时候找 BUG 找的心烦，看到他的诡异注释还是挺不错的。

15

depress

2018-09-25 17:59:10 +08:00

5

我要是接手一个项目注释这么详细，我会请那个人吃顿饭，而且这个注释好在是在代码块外，如果是代码中，注释比代码还多，影响阅读代码那体验就很糟了。

16

mztql

2018-09-25 18:03:56 +08:00

规规整整的多好啊

17

janxin

2018-09-25 18:05:31 +08:00

1

没有 fuck，表明这段注释和代码是一个人写的 XD

18

HuHui

2018-09-25 18:08:04 +08:00 via Android

工作严重不饱和

19

SamsonWang

2018-09-25 18:08:12 +08:00

注释详细点挺好的

20

maichael

2018-09-25 18:10:26 +08:00

jsdoc 的话，选填属性应该这么写

```
@param {string} [somebody] - Somebody's name.
```

21

zhangyichent

2018-09-25 18:16:17 +08:00

整整齐齐的没人不喜欢，怕的是乱七八糟不知所谓的注释。。。

22

endlessing

2018-09-25 18:26:07 +08:00

1

注释不嫌多，怕的是啰嗦表述不清的

23

zwwhdls

2018-09-25 18:28:05 +08:00

@yulitian888 写了注释，跟代码不一样才会被打呢

24

param

2018-09-25 18:32:24 +08:00

那就要问问 @returns 同学了

25

sampeng

2018-09-25 18:32:37 +08:00 via iPhone

这么多参数。提一个 obj 封装一下可好…

26

DOLLOR

2018-09-25 18:39:39 +08:00 via Android

1

注释跟代码不一致，误导读者的，才会被打。

27

zjp

2018-09-25 18:43:04 +08:00 via Android

mockio 推崇注释即文档，异常信息还带正确示范

28

anyele

2018-09-25 18:48:48 +08:00 via Android

挺好的，

29

moresteam

2018-09-25 18:56:26 +08:00 via Android

0 注释的路过

30

hheedat

2018-09-25 18:58:41 +08:00

我觉得还行

31

zwh2698

2018-09-25 19:06:07 +08:00 via Android

有枪🔫

32

firenine

2018-09-25 19:06:16 +08:00

这就体现 ts 的好处了，不用写这种注释

33

way2create

2018-09-25 19:08:32 +08:00

想起了上次那个画注释的帖子

34

cjpjxjx

2018-09-25 19:10:46 +08:00 via iPhone

2

这是前人栽树后人乘凉，比前人挖坑后人骂娘好多了

35

tangweihua163

2018-09-25 19:19:27 +08:00

参数这么多…就不是注释的问题了…

36

kerr92

2018-09-25 19:29:35 +08:00

像 20 楼说的，string/boolean/number 一般首字母小写，optional 的属性一般用中括号括起来。

37

fademeter

2018-09-25 19:31:03 +08:00 via Android

至少不会枪毙。

38

zcjfesky

2018-09-25 19:32:35 +08:00 via Android

当你接盘别人的项目的时候就知道这种耐心注释的选手简直就是天使…

39

zhzer

2018-09-25 19:32:54 +08:00

实在看不下去，可以让 ide 隐藏注释嘛

40

flight2006

2018-09-25 20:36:04 +08:00

注释是好习惯，这个注释明显啰嗦了，‘一般 xxx ’后面的都可以省略，说了等于白说

41

entimm

2018-09-25 21:01:34 +08:00 via Android

把代码写成白话文不是更好吗

42

Yuicon

2018-09-25 21:04:22 +08:00

这么一看 java 虽然啰嗦点但是可以少写很多 ‘注释’

43

sonyxperia

2018-09-25 21:08:19 +08:00

我觉得挺好

44

lightening

2018-09-25 21:09:56 +08:00

1

信息太多会让真正重要的信息无法找到

45

wsxyeah

2018-09-25 21:17:32 +08:00

命名很重要，窃以为见名知意要比写一大堆冗余的注释要好得多

46

xuanbg

2018-09-25 21:23:01 +08:00

挺好的，排版再对齐一下就更好了。

47

oxoxoxox

2018-09-25 21:26:52 +08:00 via Android

这种注释挺好的标准做法直接就能导出成文档了应该鼓励
乱写注释才会被人打

48

fundebug

OP

2018-09-25 21:28:57 +08:00

@lightening 注释应该言简意赅！

49

framehouse

2018-09-25 22:13:26 +08:00 via iPhone

有点啰嗦，不过看十行弱智注释也好过看一行莫名其妙的代码

50

gbin

2018-09-25 22:20:58 +08:00 via Android

@sampeng 参数 option 本身就是一个对象

51

neilp

2018-09-25 22:31:15 +08:00

太闲了

52

bfpiaoran

2018-09-25 22:37:16 +08:00

我咋觉得遇到这种开发就该嫁了呢

53

catror

2018-09-25 22:41:16 +08:00 via Android

写给别人使用的接口就应该写这样的注释，然而，你会发现调用接口的人还是会来问你 :|

54

PP

2018-09-25 22:41:37 +08:00

可以直接加薪。

55

lijun0926

2018-09-25 23:04:29 +08:00 via iPhone

挺规范

56

hellodigua

2018-09-25 23:05:50 +08:00

学习了……

57

hotsymbol

2018-09-25 23:07:56 +08:00

看的想死

58

imn1

2018-09-25 23:10:52 +08:00

挨打是小事……

59

nodin

2018-09-25 23:15:11 +08:00 via Android

简洁明了的注释没人不喜欢，外行人也能看明白这代码用来做什么的注释肯定是好注释。

60

jmc891205

2018-09-25 23:23:50 +08:00

2

時間久了發現實現和註釋不一樣了:(

61

fyibmsd

2018-09-25 23:26:30 +08:00

你已经是个死人了

62

SoulGem

2018-09-25 23:39:20 +08:00 via iPhone

有点多说实话，这种 option 的注释写成文档会好一点。

63

scys

2018-09-25 23:54:07 +08:00

不要对一个参数写三行注释就行。
一页纸有 80%都是注释的代码，我看不下去。

64

northernlights

2018-09-26 00:04:36 +08:00 via Android

这是在写代码还是在写注释呢？垃圾代码写的注释再多也是垃圾代码，好代码不写注释也能让人一眼明白作者的思路。

65

looseChen

2018-09-26 00:44:01 +08:00

@northernlights 你能够一眼分辨出别人拉出来的屎？抱歉话有点糙

66

kslr

2018-09-26 00:55:02 +08:00 via Android

我只会写思路和需要注意的部分

67

RockShake

2018-09-26 08:21:54 +08:00

注释可以直接生成文档的，你这样省了写文档的工作，不是挺好的么，Java 代码大部分文档不都这样生成的么，一堆人连编程规范都没读过吧。

68

Howlaind

2018-09-26 08:45:04 +08:00 via Android

干脆搞文学式编程得了

69

bk201

2018-09-26 08:47:24 +08:00

维护起来相当麻烦,注释不应该面面俱到,应该关注重点.

70

Lawlieti

2018-09-26 09:14:09 +08:00

出来挨打

71

MaxTan

2018-09-26 09:30:11 +08:00

文档注释写再多都不怕。
a = 1; //给变量 a 赋值这种直接打死

72

allgy

2018-09-26 09:31:44 +08:00

代码不够注释凑

73

aaronysj

2018-09-26 09:32:24 +08:00

参数是不是有点多

74

wqzjk393

2018-09-26 09:36:25 +08:00

1

flask 源码了解下。。满屏幕的注释

75

psklf

2018-09-26 09:39:00 +08:00

我推荐多写注释，越详细越好。

76

zhaogaz

2018-09-26 09:44:41 +08:00

最好写成类似 javadoc 的那种，能直接生成文档。

其他的注释只保留极少部分必要的就够了。

能做到以上 2 条的，基本是很优秀了。

77

kingwl

2018-09-26 09:46:38 +08:00

2

78

gesse

2018-09-26 09:50:36 +08:00

下注释的习惯是好的，不过这个代码能力有待商榷

79

TomatoYuyuko

2018-09-26 09:50:44 +08:00

同步 xhr 要被封杀么，哪里的消息

80

fundebug

OP

2018-09-26 09:57:03 +08:00

@wqzjk393 果然是这样哈哈： https://github.com/pallets/flask/blob/master/flask/app.py

81

ben1024

2018-09-26 09:57:19 +08:00

不推荐写注释，写注释是因为看代码不知道在做什么

82

zsy979

2018-09-26 10:01:32 +08:00

如果注释跟代码是一致的请他吃饭啊

83

Linxing

2018-09-26 10:01:57 +08:00

你敢不写试试？

84

Edwards

2018-09-26 10:06:01 +08:00

接受代码写得不好，但是不接受文档写的不好的，同理注释。

85

NicholasYX

2018-09-26 10:11:46 +08:00

一打眼就能看明白的没有必要写注释吧……

86

xpresslink

2018-09-26 10:14:33 +08:00

@fundebug
python 有一个专门生成文档的工具叫 sphinx，自己从代码中抽取注释生成结构化的 HTML 文档。
flask 的文档就是这么生成的。
好处是文档和代码是在一起的便于维护更新，每个人在代码里写自己的文档就好了。
最后只要生成一下就是最新的文档了，不用费力有专人去维护文档的一致性。