Home » 中文 » 客齐集 » 我们不喜欢注释 « Blog的头8年 | 高速公路编号的学问 »

我们不喜欢注释

相关帖子
作者:Jian Shuo Wang 发表于: 2010-09-16 23:09

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

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

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

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

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

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


IMG_0071
2010年9月的一次乐高日

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


Posted by Jian Shuo Wang at September 16, 2010 11:20 PM

相关贴子:
评论

我相信函数更新历史等放在注释中会比放在svn中更直观一些。

Posted by: Chairo on September 17, 2010 12:13 AM

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

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

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

Posted by: Zoom.Quiet on September 17, 2010 09:59 AM

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

招聘页面的一点建议:

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

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

Posted by: 淬念 on September 17, 2010 10:29 AM

有道理,好的代码是自明的,另外,我这里看不到图

Posted by: 下午实验室 on September 17, 2010 01:29 PM

哈哈,能不能贴一点不是核心的代码出来观赏一下

Posted by: hmy on September 20, 2010 10:39 AM

天气不错。最好的看到所有代码的方式是看一看jobs.baixing.com。

Posted by: Jian Shuo Wang on September 20, 2010 12:04 PM

背景屏幕上好像显示的是Gooogle统计?哈

Posted by: ykjsw on October 20, 2010 05:34 PM

留个脚印。

Posted by: Magnolia on December 22, 2010 08:00 PM

这个/*...*/不错,表情丰富:)

Posted by: axgle on March 19, 2011 01:47 PM
Post a comment
大名: (我信任你会填入自己的名字,而不是你的公司或者产品的名字)

邮件地址: (嘘!我不会告诉别人的)

URL: (optional)

评论:


别着急,可能要等待多达30秒钟注意:不欢迎“沙发”,“收藏”,“受益”,“瞎扯”等等简单的不表达任何思想的留言
记住我的信息?

<-- 请只按一次
Trackbacks
TrackBack URL for this entry: http://home.wangjianshuo.com/cgi-bin/mtcn/mt-tb.cgi/616
以往的帖子
支持“不靠谱的主意”就是支持创新 | 4 comment(s) | November 05, 2011
FedEx, GE和Google的文化在打架 | 15 comment(s) | July 24, 2011
不害怕优雅和美的中国人 | 12 comment(s) | May 14, 2011
我现在的桌面 | 24 comment(s) | February 17, 2011
开始活跃于微博了 | 2 comment(s) | January 31, 2011
新年快乐2011 | 11 comment(s) | December 31, 2010
菠萝和筷子的故事 | 35 comment(s) | November 29, 2010
交大,我明天回来 | 5 comment(s) | November 24, 2010
百姓网今晚在复旦的讲座 | 5 comment(s) | November 03, 2010
道路的编号 | 15 comment(s) | September 23, 2010
高速公路编号的学问 | 16 comment(s) | September 19, 2010
我们不喜欢注释 | 9 comment(s) | September 16, 2010
Blog的头8年 | 27 comment(s) | September 11, 2010
如果我有时间,我会写更短的代码 | 25 comment(s) | September 10, 2010
百姓网在威海 | 12 comment(s) | September 08, 2010
• 阅读 全部文章
© 2002 - 2009 Jian Shuo Wang. All right reserved. Terms and Conditions.
Edit