以前很难理解老程序员不写注释，不写文档，代码不规范，命名不规范。现在开始懂了。。。

代码

注释

文档

规范

124 条回复 • 2023-03-09 17:26:04 +08:00

1 2

❮

❯

1

lakehylia

2023-03-07 14:09:27 +08:00

2

你又不是做对外的 SDK ，写什么文档，写文档又不算 KPI 。

2

anakinsky

2023-03-07 14:13:57 +08:00

8

花那时间干嘛，早点下班不好嘛

3

jeremylai

OP

2023-03-07 14:18:19 +08:00

@anakinsky 确实是呀

4

zzzzz001

2023-03-07 14:18:40 +08:00

4

确实，突然悟道了，怪不得我 2 年毕业 2 次

5

j717273419

2023-03-07 14:25:26 +08:00

33

不要想太多，其实就是工期紧，如果工期不紧，我还想加 unit test 呢。现实是刚上线一个，另一个项目马上来了。没有喘气的机会

6

chendy

2023-03-07 14:25:43 +08:00

3

有限的时间内做足够的事情就行，满足需求，不用太好，别太垃圾，不给后人挖坑，也不给后人铺路，完事
加班加点把事情做得很好，说明有能力有责任心，但是这个东西要让领导看见、要让领导理解、要让领导认可，否则多少浪费时间
至于什么不可替代性…吃屎是老码农基本功，而且如果恶心不到别人天天恶心自己也不是那么回事

7

hervey0424

2023-03-07 14:26:03 +08:00

有文档但是没有及时更新, 这个还不如没有文档, 看文档还不如不看, 但是别人觉得有文档很容易

8

buffzty

2023-03-07 14:27:53 +08:00

1

我代码中几乎不写注释,api 文档会写在 wiki 中,代码规范,命名也规范.
当你代码规范命名也规范时根本用不着写注释. 目录名函数名变量名就是最好的注释

9

jeremylai

OP

2023-03-07 14:33:54 +08:00

@zzzzz001 悟了悟了，哈哈哈

10

jeremylai

OP

2023-03-07 14:35:23 +08:00

@chendy 是的，做好基本的要求，只要不犯很大的错，就无所谓。我说的是可以替代性，和你说的不一样，只是没那么容易替代

11

vagranth

2023-03-07 14:52:17 +08:00

32

程序员悖论嘛。

你架构做得好，代码易读易扩展，随便谁都能接手。你是可有可无的人。
你代码写得好，没什么 bug ，天天不加班。你是工作态度不积极的人。
你代码写的不好，bug 成堆，天天加班。你是公司的骨干。
你架构一团糟，代码除了你自己没人敢碰。你是公司的重要人物，项目没你就垮了。

12

optional

2023-03-07 14:53:23 +08:00 via iPhone

大部分注释都是多余的

13

yvescheung

2023-03-07 14:59:15 +08:00

文档还是要写的，只不过是写给自己看，不然过段时间自己也看不懂写的代码了

14

fsdrw08

2023-03-07 14:59:36 +08:00 via Android

1

问题代码不加注释，过了段时间后，连作者本人都不知道写了个啥那怎么办？

15

Hurriance

2023-03-07 15:04:33 +08:00

我觉得更多的不在于技术上的问题，或者某一个人的问题。

16

changhe626

2023-03-07 15:06:05 +08:00

2

就国内的情况还写文档，你能把功能开发完了就不错了，一个迭代接着一个迭代，恨不得两个迭代放在一起做。你有时间把代码写完就不错了，还文档，测试的代码，想啥昵

17

rationa1cuzz

2023-03-07 15:09:11 +08:00

关键是开你也不会考虑你的工作有没有人接手啊，又不是一个人干一个项目

18

lambdaq

2023-03-07 15:10:19 +08:00

以前写文档的原因是很多场合是重工业和军工，写文档的人都是有 pension 有编制的，把编程当成一种为客户服务的事业在做的。。。

19

jjwjiang

2023-03-07 15:10:46 +08:00

2

个人觉得，如果不写注释的代码看不懂，那这代码多少有点问题

20

bfdh

2023-03-07 15:13:28 +08:00

6

并不认同这个观点。
我觉得根源在于公司管理混乱，对这文档没有要求，项目时间规划的时候根本就没预留写文档的时间。
一段代码写完之后，后面都是修修补补，维护久了，实在无趣。所以我巴不得赶紧把自己写的代码交出去，有个靠谱的人继续维护，而我自己可以开始更有挑战性的工作。

21

karmaisbitch

2023-03-07 15:28:26 +08:00

复杂业务还是得写一点注释，经常过个半年回来看代码都忘了当初为啥要写这一段

22

jorneyr

2023-03-07 15:30:32 +08:00

但行好事，莫问前程。

23

jeremylai

OP

2023-03-07 15:32:32 +08:00

@karmaisbitch 就是更多的是为了自己考虑，少为公司考虑，不然到时候就容易的开了

24

yuancoder

2023-03-07 15:40:32 +08:00

大部分情况下看不懂代码，并不是真的看不懂，而是不知道为什么这么写。
这跟写不写注释关系不大，如果注释只是在描述这段代码在干什么，过一段时间后，还是不知道为什么这么写。

25

ghostben

2023-03-07 15:43:24 +08:00

5

说起来之前写了一个 vscode 的插件，作用就是在本地对代码进行注释，只有自己电脑才能看到。感觉是不是也有不少人有这个需要？

26

AlexHsu

2023-03-07 16:04:35 +08:00

写文档注释这种事就是将心比心的事儿正常开发的工时至少的给出一半来写文档不给时间自然就不写没什么可说的

27

lessMonologue

2023-03-07 16:05:44 +08:00

@ghostben 老哥发出来吧，刚需。目前是通过 bookmark 功能来用的

28

ZSeptember

2023-03-07 16:13:23 +08:00

虽然但是，代码写的烂，可替代性还是强，该毕业还是得毕业。

29

changnet

2023-03-07 16:25:30 +08:00

19

对于工作了 10 多年，有那么一点点管理经验的我，是不认同这个观点的。

凡是不定注释，代码不规范的在我眼里都是工作能力不行的，绩效不会很高，工资、职位提升也很有限。如果要开人，第一个开的就是这种人。

代码是评价一个程序员最直接的东西了，你丢给别人一堆垃圾，期望别人对你大加赞赏，升职加薪？你觉得这逻辑走得通么。故意这么搞，最终就是落得人走了，名声在同事里也不好，领导觉得能力也不行。

开发时间太紧，需求频繁变更导致代码可读性不好，这还说得过去。但你至少写出一些工整，规范的代码给别人看，让别人知道你的能力是很不错的啊，这才有可能给别人留好印象，无论是升职加薪，还是以后介绍个工作，内推一下，都有可能。

你如果觉得公司给的钱不够多，那你可以慢点干，出的活少一点，但至少活还是干得漂亮的。或者你直接跳到个给的钱多的公司，那也能理解。

不要迷信什么不可替代，程序员 99.99%的活都是给钱就有人能干。那些代码写得工整规范的程序员也能干，无非就是又跑到某某论坛发个帖子大骂前一个老员工留下一堆垃圾。

对老板来说，开人的时候压根没想过你活干得怎么样，人家是从成本核算来开人的，好的不好的都开了

30

dqzcwxb

2023-03-07 16:28:28 +08:00

6

31

yaphets666

2023-03-07 16:31:48 +08:00

@changnet 问下大佬，你们团队是规定所有代码都写注释吗？我没有在特别规范的团队干过，想了解下

32

jeremylai

OP

2023-03-07 16:37:02 +08:00

@changnet 如果公司按照代码规范，注释来做评定绩效、工资的参考的话，那我肯定会注意。问题是我公司不是呀，既然不是，那为啥要这样做

33

changnet

2023-03-07 16:37:22 +08:00

@yaphets666 我们公司做得并不是很好。规范有要求要写注释。但有些人不写，也没有强制的措施，公司没有 svn hook 或者 ci 之类的东西来做检查。只是偶尔看到会口头说一下

34

tediorelee

2023-03-07 16:39:08 +08:00

像我们公司不允许随便写注释的有没有，除非涉及到特殊的业务需要解释

35

jeremylai

OP

2023-03-07 16:40:52 +08:00

@changnet 既然没有强制，只是偶尔说一下，那多做了，为了你的理想工作吗？如果只是你个人主观意愿，没有回报，一次两次没啥，经常这样子，不就是欺负老实人吗

36

aliveyang

2023-03-07 16:43:10 +08:00 via Android

人的问题，有些人不讲究，有些人不将就

37

changnet

2023-03-07 16:47:43 +08:00

3

@jeremylai 你不这样做，怎么培养你的编码习惯，怎么提升你的编码质量？难道说在公司写 5 天垃圾代码，周末 2 天就按自己的规范写好代码，能分得这么清？

你在公司不好好写，以后你的同事跳槽了，敢内推你去再做一次同事吗？你的同事出去创业了，看到你代码一团糟，敢带你吗？

你这不是自己坑自己么。你对当前公司不满，有很多种方式可以处理，为什么选择这么一种来坑自己。你觉得对公司有什么损失吗？对公司而言只要代码能跑，钱赚到就完事，你同事多加班两小时去整理你的代码，对公司来说不算事。

38

myselflove8090

2023-03-07 16:48:05 +08:00

不要迷信什么不可替代，程序员 99.99%的活都是给钱就有人能干。。。。。。。。。

39

Felldeadbird

2023-03-07 16:48:09 +08:00

楼主错误理解，走火入魔。

代码可读性强不代表可替代性高啊。你说 linux 的代码可读写怎么样？

老板铁了心要优化你，后面的人接手只要花时间一样可以读清里面的逻辑。

你想想你一个人把公司打理得规划整齐。你被裁了后，后人可不一定有你这般水平的。到时候要试错 N 次都不一定解决到。

40

myselflove8090

2023-03-07 16:49:45 +08:00

想起国外那哥子上班外包给中国人的事。。

41

Fule

2023-03-07 16:49:50 +08:00

这种“人工混淆”是全局杀伤，包括几个月之后的你自己。几个月之后如果你需要改代码，也不比别人有多少“优势”，除非你记忆力超强。而且改代码也会更耗费时间，以前“省”下的时间在改代码的时候都会补上，而且每改一次就补一回。如果组里大家都这样，想想每个人都释放全局杀伤的场面，我觉得属于互相伤害。我觉得老代码那些问题，部分属于能力问题，部分属于赶工期原因，为了你说的理由而那么做的话，我觉得是得不偿失，除非是抱着跑路心态。

42

zpxshl

2023-03-07 16:59:50 +08:00

之前有个前同事面我现在的部门，领导问我对这个前同事了解吗，我想起了他的代码水平...

43

8355

2023-03-07 17:06:14 +08:00

1

可预期的被喷了
有些事懂了就懂了但你说出来就不好了，分明是大家排期紧工作忙忘记写了🤪，你这样说就成了恶意乱写。
每个公司有自己的工作方式，懂的自然懂。

44

xiaoxiaoming01

2023-03-07 17:07:51 +08:00

@ZSeptember
还是要看写烂代码是 [故意的] 还是 [不小心的] 🤭🤭

45

superedlimited

2023-03-07 17:09:30 +08:00

jetbrains 家的 ide 写代码的话，推荐一个插件，private note ，只能自己看到的注释：）

46

misaka20

2023-03-07 17:27:44 +08:00

大部分人蜜汁自信。
我觉得以国内复杂的需求，该写注释还是写注释，大部分人没那么能力写读性高的代码，还是老老实实地注释吧。

47

wqhui

2023-03-07 17:38:10 +08:00

哪怕变量、方法自认为命名的很好，注释也是有帮助的，毕竟中国人母语不是英文，看纯英文可能 get 到的意思有点不一样。而且命名一般也不会很长，几个单词就能解释清楚做了什么吗。给的开发时间充裕写详细一点，时间紧就简单写一些特别重要的

48

charlie21

2023-03-07 17:55:40 +08:00

今日谬论 1/1

49

UIXX

2023-03-07 17:55:45 +08:00

1

老生常谈，程序员付出了更多时间跟精力无法获得实质回报...

我一般将这类问题归为，系统性管理问题。之前的帖子有讨论过。

50

Raven762

2023-03-07 17:56:44 +08:00

就我们这测试都省了，每天一个变更还有不知道哪来的鬼点子，这周要的功能下周就又改了，还写个🔨注释呢

51

zmqking

2023-03-07 17:58:44 +08:00 via iPhone

当头棒喝……悟了

52

tkHello

2023-03-07 17:59:02 +08:00

恭喜进阶

53

tkHello

2023-03-07 17:59:41 +08:00

队伍壮大了一点点。一点点一点点一点点一点点 ... ... ...

54

cangcang

2023-03-07 18:02:53 +08:00

@changnet #29 这些道理建立在一个大前提上。公司给员工的涨薪幅度能追得上跳槽的涨薪

55

Aixtuz

2023-03-07 18:07:12 +08:00

目标是作品，那我怎么完美怎么来~
目标是收入，那你考核什么，我重视什么。

56

mrzx

2023-03-07 18:34:12 +08:00

@changnet 首先，非常认可你的说法。任何人都是可以被替代的。

但是~~~~~~替代的难度是不一样。我宁愿给你加难度或者我走了你得重构。重构得花资源，得多花钱，哪怕对于老板来说是九牛一毛。我开兴就行。

而且很多时候不是不加注释，是肯定要加注释的，良好得编码习惯很重要。要对得起自己，并且自己会整理出来一套文档，但就是不给公司罢了

要说我这样的，你们公司不要，无所谓，我们还没沦落到去你们这样的公司。。。而且现在开发工作细化，每个人就负责那么一小块部分，明显就是资本家为了开发效率和提高替代性衍生出来的产物。那真的就是码农了

要知道以前像运营商级别的业务系统，很多就只有 1~2 个人开发出来的，正因为如此，很早的程序员技术不错，因为被逼的什么都要接触，前端，后端，数据库，操作系统，内核等等。。。到现在乙方公司还不敢动他们。除非等这套系统在运营商彻底淘汰。

现在的程序员。。哎。。一言难尽。。

57

pkoukk

2023-03-07 18:52:15 +08:00

1

我觉得我代码写的像诗，不需要注释
我的同事觉得我的代码写的像屎，太过抽象无法理解
就算是诗，也有鉴赏等级的，很多经典意象和引经据典的东西，没学过他就是读不懂

所以，工期赶得不紧的时候我还是会写注释的
为了兼容水平参差不齐的同事们

58

nothingistrue

2023-03-07 19:24:34 +08:00 via Android

1 ，过时的注释 /文档，比没有注释 /文档更可怕。2 ，要想注释 /文档不过时，成本非常大。认不清上面这两点的程序员，要么不够老，要么是人来经验不来，要么是假技术实管理（尤其是没编码几年就混上总监的）

59

BUHeF254Lpd1MH06

2023-03-07 19:35:04 +08:00

说真的有些特殊判断加注释我可以理解，普通函数，每行代码都加就没有必要了吧。拿函数名来举例，正常来说，你函数名起的够有概括性，代码拆分够好的话，都不用写注释，直接看函数名字不知道行了

60

Mandelo

2023-03-07 19:56:00 +08:00

只要给时间,都好说.
没人喜欢免费下班写文档

61

wanguorui123

2023-03-07 20:01:47 +08:00

想太多，公司不行了，该裁一个也跑不掉，留几个运维能重启机器就可以了，运维才是不可替代的

62

hello2090

2023-03-07 20:05:41 +08:00

不可替代性还不简单么？给公司大门上把锁，没有你公司开不了门，这不是无可取代？

63

realpg

2023-03-07 20:41:07 +08:00

不写注释的代码很多
基本就是看方法名就知道是干啥的
功能模块拆分合适
里面怎么实现的基本合格程序员都简单清晰看得懂

你想重构你就重写好了

64

jeremylai

OP

2023-03-07 21:13:20 +08:00

@tkHello 对头

65

javlib

2023-03-07 21:14:39 +08:00

最近用了 copilot ，爱上了写注释，注释写的越多，copilot 生成的越准。

66

charlie21

2023-03-07 21:19:49 +08:00 via iPhone

code review 想不想过啦？

67

opengps

2023-03-07 21:21:02 +08:00

注释是写给自己看的，很多逻辑自己确实已经不需要注释了，当然会慢慢的都不再去写注释

68

KimiArthur

2023-03-07 21:54:24 +08:00 via Android

@vagranth 所以只有 OSS 才是真正的软件开发！

69

securityCoding

2023-03-07 21:56:22 +08:00

满足 lint 即可

70

whyrookie

2023-03-07 22:12:58 +08:00

不重构可以理解，完全不写注释理解不了，一些比较晦涩的代码写一下注释也不会花多少时间，越来越觉得代码写规范一些是对自己的要求，和公司没啥关系。

71

sniperking1234

2023-03-07 22:34:04 +08:00

写设计文档，代码命名规范，写注释不是基本操作吗，这帖子里面很多回复让我疑惑

72

loveour

2023-03-07 22:35:23 +08:00

不能赞同这个观点。真正导致被替代的肯定不是注释写得清楚。
另外，也不赞同好的代码习惯可以代替注释。好的代码习惯可以替代很多注释，但是总会有注释更好更清晰更易懂的时候。尤其是需要做一些兼容工作的代码，有时候不注释别人还以为代码没用，其实是为了解决一些稀奇古怪的问题。

73

leon0918

2023-03-07 22:47:12 +08:00

代码需要自解释，有些 code review 会要求

74

b123405060

2023-03-07 22:47:57 +08:00

好的代码, 目录, 类, 方法, 命名, 层级清晰, 有没有注释都行!

75

cp19890714

2023-03-07 23:11:34 +08:00 via Android

2

公司管理塑造员工。什么样的公司出什么样的员工

76

CoderLife

2023-03-07 23:14:56 +08:00

if (a == null ) {
//判断 a 是否为空
}

77

ivvei

2023-03-07 23:41:07 +08:00

主要还是从方便自己出发。写了有收益就写，没收益就不写。
代码可读性这种东西就不要追求了。能不能看懂，和读者的背景、水平、习惯也是很有关系的。代码规范命名规范之类的跟狗屁差不多。网上代码那么多，几个符合你的规范？光缩进风格都有好多种。差不多得了，提高自己的适应能力才是真。

78

FreshOldMan

2023-03-07 23:41:28 +08:00 via iPhone

不写的话过一段时间你记得住这些垃圾代码吗

79

HankLu

2023-03-07 23:56:18 +08:00

我还故意留下 bug ，留下后门，留下验证，留下过期时间。我走了几个月，保证这个 app 就用不了！

80

THESDZ

2023-03-08 00:03:08 +08:00

你是通过自伤 800 达成了伤人 1000,建议跳槽吧.

81

dcsite

2023-03-08 00:27:33 +08:00

@8355

出发点不同，写注释和文档的热情肯定也不一样。就拿开源软件来说，有的尽量文档注释特别细，有的没有注释逻辑还特别绕，不能说谁对谁错，都有自己的目的……

写的代码太简洁好用，下场就是有你没你都行；写的代码是天书，大家虽然心里骂你，还得看你脸色行事：）

就像你说的，看得太多了，懂的都懂。

82

dayeye2006199

2023-03-08 01:41:11 +08:00

懂了，k8s 这种 i 项目注释文档都很齐全，所以我上我也行，我也能做 core contributor ！

83

jadec0der

2023-03-08 06:49:39 +08:00

2

我也工作快十年了，从外包公司一路干到美国的大厂。据我观察，工作能力和前途大部分时候是正相关的。

一类是工作非常出色的人，你明显感觉他在这个公司鹤立鸡群，他经手的代码都很漂亮，如果要转给别人做，接手的人都会表示学到了。他们不担心被替代，反而公司会担心他们跳槽，但最后遇到好机会他们都跳槽走了。

另一类是很会混日子的人，同事不想和他们合作，PM 会避免把需求交到他们手上。缺人的时候公司不会动他，但是市场转冷的时候首先被裁的是这些人。

至于你说的工作做的不好，但是特别会刷题面试的人，我也遇到过很多，从小公司里看，是一个干活不好的同事靠刷题跳进大厂，工资翻倍的故事。从大厂里看则是面试失败，招进来一个光会说不干活的人，如果实在太差还要在试用期结束前劝退。毕竟如果工作能力不行，在什么公司里的发展都有限。

84

8355

2023-03-08 06:57:01 +08:00

@dcsite #81 开源软件大多是为爱发电，是真正自己想干和热爱的事儿，而公司的项目更多的是糊口，不能想怎么干就怎么干，还得考虑团队能力 /后序维护的人 /内部规范 /为业务未来可能存在的变动留下冗余扩展接口 /救火 bug 的临时修堵等等，这些可能都会让代码变的不再极致。
开源项目绝大部分应该都是作者自己维护，了解所有代码和掌控未来的发展趋势一切东西相对确定不可控因素会大大减少，可能花 5 天 10 天时间研究一个算法或者架构能让性能提升 10%，这对自己十分有价值，对公司来说你花 5 天 10 天研究这个还不如多迭代几个版本写点新功能来的实在，只有业务量足够大特别需要这 10%性能的企业才会足够重视这个行为，但是绝大多数人是进不了这种公司或者到不了这种公司的这个岗位。