我们不喜欢注释

今天下午的乐高,讨论了代码规范中注释的部分。做为实用主义者,我们不喜欢过多的注释。“让代码的速度跟得上思考的速度”是我们一直提倡和追求的,也就是代码要写得入如注释般清晰,简洁,让人可以如读英文文章一样的读代码,而不是读注释。

我们干掉了所有PHPDoc才认识的东西,就是/** @param这样的东西,,另外注释统一了用两个斜杠(//),而不用斜杠星号(/*…*/),以强化就算有,也要短到一行的意思。

当我们强调注释或者文档的时候,或许是在解决错误的问题。越长的注释,就意味着越过期的注释。

我们反对过度文档,而尽量用最简洁的代码来取代它。与其在注释上花功夫,不如在函数和变量的命名上多推敲,花时间多做重构,把分层和封装做好,把抽象做好。

“没有比提高一个没有必要的事情的效率更没有效率的事情了。”一次一次在开发过程中被验证。

说到底,写代码如同写文章,有十几种不同的写法,无非在“推”和“敲”两个都不错的字中寻求最佳的那一个,或者在一个恶心的A和一个恶心的B之间徘徊,绞尽脑汁寻找一个不是那么恶心的C。说到底,没有绝对的对和错,只有合适与不合适。一群人,在一起磨合出来一种共同的思路,才是有力量的开发团队,否则只是乌合之众。

IMG_0071
2010年9月的一次乐高日

后注:看看我们刚刚做好的一个页面

《我们不喜欢注释》上的9个想法

  1. 是也乎,是也乎!
    – 没有意义的注释比没有注释要邪恶!
    – 有注释的烂代码也比烂代码要恶心!
    – 没有注释的烂代码比烂代码更恶心!

    代码的可读性比注释要靠谱,
    用doctest代替注释要爽直!

    但是,认真/真实/同步的注释,特别是有文档化输出的注释,真的是非常有价值的…
    当然,如果我们的代码永远没可能被公司以外的人见到,那么注释就是练习输入了…

  2. 代码我不专业,审美我还可以

    招聘页面的一点建议:

    第一,沙滩合影色调需要处理一下,有些阴暗,需要给人光明前景的感觉。

    第二,“雁阵”的后面增加几个空白的人型轮廓,加个箭头的指向,符字“这是你的位置”

发表评论

邮箱地址不会被公开。 必填项已用*标注