发现很多人写代码没有很好的 design ,没有 document 没有 test, 没有 test coverage , 没有 sphinx。

[nooper]

写的项目只有自己明白，剩下的基本没人看的懂。
structure of your code should avoid reference cycles.
better variable naming.
哎呦，我实在搞不懂code quality, 不是写出来多么牛B的算法，多么牛逼的技术，而是你的东西能够被人看懂，能够让他人学习。
即便是最简单的代码，也要很整洁，高质量的代码是消除复杂的结构，和混乱的代码。
而不是写的多么复杂，不是用行数来衡量的。
看来大部分人普遍需要提高质量，同样我也需要。
木哈哈哈。

你们还是得过且过的，说明你们的理念和认识不够深刻。

和老外协作几个开源项目试下。我以后就有功夫就pull request 开源的高质量项目，你的程序理念.你们还知道cmm5认证是什么嘛

[andychen20121130]

为了让老板看不懂啥也不写。

[andychen20121130]

哈哈。。。。。。。。。。

[em70]

你写代码是为了让他人学习么，大都是为老板赚钱，能实现功能就可以了。文档齐全，代码工整，这是个人素质而已。

[messense]

以前也很随意，现在倒是努力认真写了。Example:

https://github.com/messense/wechatpy

One man work. 话说 Travis CI、Coveralls、ReadTheDocs 和 Scrutinizer CI 这些集成 GitHub 的工具真的不错。

[nooper]

@messense 没有代码注释没有注释的代码不能称为好代码，看了一下代码的质量可以。没有细看

[messense]

@nooper 写的时候公司项目赶着用，注释写得就比较少，而且本身逻辑也比较简单啦。

[nooper]

@messense 基本没有注释。哪怕是再简单的逻辑也要有注释。好的习惯和好的细致程度能看清楚一个人的真正的品质。numpy pandas都有注释。任何一个伟大的项目的成功都是源于细致和良好的素养。我总算认识到这一点，项目再赶，说明公司的流程和文化上就没有培养人的意识

[nooper]

@em70 我写的任何一个项目都可以成为开源项目。我的意思不是说在Github上开源。开源项目是有开源项目的标准的。这是我要努力和致力的。

[messense]

@nooper 是啊，公司大部分时候都是在赶项目......不过注释是有一点的...为了用 Sphinx 自动生成类的文档特意加的......也是希望能有时间完善，但是精力暂时有限。能养成好的习惯自然是很好的事情，做起来阻碍还是挺多的。继续努力呗。

[nooper]

@messense 希望加上哈哈。逼死人的节奏肯定离职。

[em70]

@nooper 职业程序员的代码版权属于公司的啊，不能你说开源就开源。

[nooper]

@em70 我自己的项目啊，跟公司无关

[ilili]

我觉得楼主说的就是我这样的。。。

[songco]

根据我们公司的几个美帝高级码农的代码(差不多都有15+年的经验, 职位比较高, 但是都还是一线码农), 不写注释什么的基本上问题不大, 他们的代码都非常清晰好懂. 不过他们的test非常多.

另外我做过的另一个用c写的比较底层的项目, 基本上只用比较小的精英团队, 也没注释unit test之类的, 项目质量还是非常好的. 不过大部分项目都没办法只用水平比较好的程序员, 比如我在同一个公司的另一个项目就比较惨, 老大给我分了好几个应届生(学校都不错, 基本都是国内排名前10的..),我不太想要, 老大直接来了句, 我给你的人不是人吗? 项目比较紧, 新人没时间人力去培训, 又不能闲着, 让写代码吧, 你review/修改代码/fix bug的时间比他写代码的时间还要长, 让他们先去管理服务器吧(我们项目的服务器比较多, 组里大概有几百台), 他们的经验又不够, 做做测试吧, 我们测试:开发比例已经1:1了...

[wffish]

做个标记，做个记录，自己能找到就行了。大部分时间都是这样。

[coofly]

有个理念是：
需要注释说明你的函数、变量命名不够明晰，说明你的结构不够清楚。
好的代码自己会说话，不会说话的代码请回家重构去。

[timbotetsu]

@nooper 没有代码注释没有注释的代码不能称为好代码

我个人认为代码即文档，希望别人看到我的代码的时候只要扫一下我的方法名就知道我这个方法是做什么的，变量名代表的意义
因为在工作中别人会看到我的代码，所以我会积极的把代码写得更好一些，反而对自己非工作时候写的代码得过且过（因为没人看ry

[nooper]

@coofly 错误。

[coofly]

@nooper 请证明

[coofly]

@nooper 好吧，不需要证明什么，这种问题其实挺主观的
只希望你知道有这种观点存在就好了

[sennes]

带师弟妹做FPGA项目的时候也觉得不管写多简单的模块、写多短的代码都要考虑一下`可能会看到你代码的人的感受`要让别人容易理解并且能利用、修改你的代码(不管是代码本身写得易懂、还是通过注释、还是通过文档)
我个人觉得一份好的代码是给别人可以重复利用。如果你写得太混乱，虽然在你用的这个项目是run起来了，但是别人想稍微修改一下都无从下手那就不是好的代码。

[yangzh]

楼主高冷

[guoqiao]

说说个人的习惯:
1. 如果看到一打开都是长篇大论啰哩啰嗦的注释的源代码, 即使注释很工整, 我也会感到很烦躁. 能不能直接上干货? 尤其是很多时候, 注释只是为了凑数.
2. 阅读代码时, 我一般会跳过注释直接看代码, 因为注释经常会骗人(例如代码修改后注释没有同步修改), 而代码不会. 只有代码不够直观的时候, 我才会参考下注释, 但也只是参考而已.
3. 好的代码本身是最好的注释. 与其把时间精力花在写注释以及注释的排版上, 不如花点心思优化代码.
4. 这个问题其实跟你使用的语言有很大关系. 如果你是C/C++程序员, 由于指针内存模板等诸多语法问题会干扰你理解代码逻辑, 所以需要的注释多一些. 而对于 Python 等直观的追求简单的语言, 大部分时候代码就像自然语言一样, 可以自解释了, 无需多言.

[raincious]

再忙代码注释也是要写的，一方面帮助自己整理里思路，一方面防止自己也忘了。

我找来自己写的两份代码，一个有注释，一个没有，自己感受下就明白了，看完之后说说你想维护哪一个：
https://github.com/raincious/facula/blob/master/src/Facula/Framework.php
https://github.com/raincious/facula/blob/d5f29e9b00690d4221e6a32298e5c2efd52faa9a/facula.php
（是的，这是一个框架下的同一个单元。当然，版本不一样。）

测试也是要写的，否则重构要跳楼了。

@guoqiao

这是很明显坑踩得不够多啊。2、3两条根本是人为原因。

[pepsin]

好的代码自己会说话，另外我觉得好坏程序员的标志是 Commit 的平均加减代码差值有多接近，净增的那种基本就是代码坨大师，危害巨大。

[vietor]

注释是邪恶的，要尽量少；命名才是王道。拆分成单引用的小方法是无耻的，紧凑更合适

[lightening]

请问 Sphinx 是啥？

我们公司 guide 要求尽量不写注释。我们认为注释是一种偷懒的办法，因为代码易读程度不够，所以只好靠注释来弥补。（ 我们用 Ruby。C 和 Java 等语言本身语法上、性能要求上不容易做到简洁明快，写注释完全没有问题。 ）

[lightening]

举个例子，我们认为以下代码：

if some_condition?
do_something
end

def some_condition?
...
...
end

def do_something
...
...
end

比以下要更易读：

# some condition is true
if ......
# do this and that
...
...
end

当然 some_condition 和 do_something 的名字要仔细斟酌，以至于读者一看就知道啥意思。
这是当代语法简洁的语言（Python、Ruby 为代表）中比较普遍的思想。

[guoqiao]

@raincious
1. 就是因为踩过很多坑, 才知道注释不可信.
2. 确实是人为, 因为写代码的始终是人.

[reeco]

有的代码确实是写了详细注释也看不懂的

[est]

从前有个工程师有 很好的 design ,有 document 有 test, 有 test coverage , 有 sphinx，最后他完成项目之后被开除了。公司花2000工资请了个中专生代替了他。

[wudikua]

矫情

[yjsslab]

注释 比 代码 难写！哈哈。

另外，你们觉得 码码水平是不是真的也和写作/表达能力密切有关呢？

经常表达能力差的人都是使用 a, b, c, xyz 做变量名的。。。有没有

[yjsslab]

@est 不明白。。。求解释

[yjsslab]

做程序员又不需要认证/备案，门槛太低，每个人都可以说他是程序员，没有质量保证是肯定的啦！

[nooper]

@wudikua 无不会雇佣太垃圾的码农。

[chocotan]

公司赶项目+10086......
唉.....自己默默的努力....

[nooper]

@est 说明一开始就进去了一个非常垃圾的公司。

[chisj]

看过一个老毛子的代码，更坑！

[hitsmaxft]

如果一个团队重视技术, 那么代码质量就会越来越好.

一切代码质量问题, 说明这个团队的技术氛围不佳.

[walleve]

@hitsmaxft bingo

[cdxem713]

感觉楼主讲话带刺，看着好难受啊

[jimiton]

@cdxem713 同楼上，看着好蛋疼

[cdxem713]

我的理解是，代码如果整体结构很好，变量名、方法名、类名等都起得很合理的话，是不需要很多注释的。
例如这个项目的代码：
https://github.com/Leaflet/Leaflet/blob/master/src/core/Util.js
没有很多注释，但是也非常容易理解

另一个开源项目：
https://github.com/openlayers/openlayers/blob/master/lib/OpenLayers/Util.js
不知道有多少人愿意看下去，其实注释量还挺大的

[wudikua]

@nooper 码农何苦为难码农，能胜任就好

[RemRain]

```
基本没有注释。哪怕是再简单的逻辑也要有注释。
```

楼主太绝对了，完全是为了追求注释而注释。写得好的代码，不一定需要注释，因为代码已经表示出了意思，注释反而是干扰。作为程序员，我更喜欢代码自注释、紧凑的代码，比如这样：
```
int max(int a, int b) {
return (a > b) ? a : b;
}
```
如果非要在前面加上注释，标识这是求两个数最大值的函数，你说这不是废话是什么？

另外，注释往往会误导人。你不知道你写的这一段代码之后会经手多少人，会被改动多少次，而且每一次都能顺带更新注释。从我接手过的项目来看，都会有那么几处的注释是带误导性的。

注释还有一个问题，就是增加维护的工作量。注释越是密集的代码，越是没人敢改。函数外的注释还好，函数内如果有密密麻麻的一段注释，那注释对应的代码基本没人敢动。

[qianlifeng]

我们公司要求尽量不写注释，逻辑复杂且必要的情况下可以写一点。前提是要命名，逻辑啊什么的要清晰易懂。

[nooper]

@RemRain that's snippets.that 's not the function, nor the implementation.
that's the code could be any part of the project. You don't get the means of the code quality. what if there is not any document, any comment in the code , if you want to use some framework , do you know how to use it? if you can , you can try to hack some code and design some web framework, data analysis framework or some middleware of any program languages ,ask anybody could learn and know how to use the your design or not? have you done any part of time to patch some bugs or some features in the open source project, try to make it. Then let me know. I worked with financial analysis system for a while. Each pieces of the code must work perfect!

[ericFork]

看了这么久，楼主，talk is cheap, show me your code

[RemRain]

@nooper 请注意，我反驳的是你```哪怕是再简单的逻辑也要有注释```这个观点。

代码不都是框架，在我眼中，一句简单的 echo "Hello, world!" 也是代码。只要做到逻辑清晰，命名恰当，看起来舒服易懂即可，注释只是点缀和补充，这一点，redis 和 nginx 的源码都做得很好，不信您可以看看，感受一下。

无论是写代码，还是人与人的交流，目的都是让别人明白自己的意思，通俗易懂大于逼格。讲两句话蹦出一个```你们还知道cmm5认证是什么嘛```，回复几次就干脆用英语装 X，很难让人看出你想正常交流。

另外，作为轻度强迫症患者，建议你在书写英文时，句首字母大写，标点紧跟字母，习惯性地在标点后面加上空格，并注意单复数的正确使用，这样也有助于您正确地书写代码。

[neutrino]

@RemRain 哈哈还要在中英夹杂的时候注意英文前后的空格

[RemRain]

@neutrino 哈哈，这个倒是只要自己遵守就好，没必要强迫别人来着。提着这个，要不我再补充一点？无论是注释还是书写，使用缩写的时候请使用全大写字母，如 cmm5，请写成 CMM5。否则给人一种不专业的感觉。

[ahtsiu]

// 此处可能有坑
trap(you);
/* Order matters */
trap(me);

/**
*will NOT throw any exception
*/
void trap(man who){}