如何让自己写的代码易维护?

在知乎上的回答:http://www.zhihu.com/question/20039541/answer/13773509

代码易于维护,分为两个方面:容易阅读理解;容易修改扩展。

一、如何写出容易被阅读和理解的代码

1. 最根本的一条,要向写文章学习,有目录,有大纲,有标题,有段落,有适当的提示。

1.1. 首先是目录结构,这个在一些比较好的实践中,有约定俗成,比如Rails应用,app目录下一定分controllers、models、views、helpers四个目录。再加上config、lib、vender,大致的代码在哪个位置,不用猜都知道。

越是常见的项目类型,越是应该按照约定俗成来构建项目的目录结构,不要别出新裁。

对于没有业内参考的项目,目录结构也尽可能采用简单、易懂、含义固定明确的单词,比如:core、config、test这样的命名。

1.2. 包名与文件名,在这方面,java语言的规范非常值得其他语言参考和借鉴,分层组织,合理命名。是最重要的。

1.3.一个源代码文件里,要不要有注释?我认为,尽可能不要,还是要像写文章一样,让人阅读起来,有感觉。比如:文件名,类名,方法/函数名。如果将所有的实际代码全部折叠起来,顺序的阅读这些名字,能不能让阅读者,对于这一个源文件的内容和目的,有大概的了解?

再强调一次顺序阅读,一个 源程序文件内有很多个函数/方法,这些方法的排列次序,是有意义的。仅仅依靠调整次序,比如:构造函数,扩展构造函数,简单的读写函数,业务相关的函数。以这样的次序来排列,会更加便于阅读。

在必须写注释的地方,也不要写得太多,言简意赅,把要点用1.2.3.讲清楚。

1.4. 变量名,常数名,我们必须一再一再的强调命名的重要性,可以说,命名是软件开发中,头等重要的大事。要简洁、清晰、全英文(决定不要汉语拼音、任意缩写)、尽可能不要夹杂数字,比如var1、var2这样的变量名,就是最糟糕的。

2. readme

在项目开发的过程中,定期整理一份readme,放在项目的根目录,主要包含两部分内容:我们的代码做了些什么?如何查找我们写的代码。

3. wiki

团队开发,尽可能维护一份wiki,自己架一个mediawiki或者其他wiki,都是很简单的。或者自己架一个redmine这样的集成项目管理工具,该有的就都有了。

wiki的管理维护是一个很大的话题,这里就不再展开了。

4. 单元测试

@李楠 和@KevinWei 已经提到了。 这个办法,既方便阅读理解代码,也方便修改代码。非常重要。

5. Code Review

@KevinWei 也已经提到了。

二、如何写出容易被改写和扩展的代码

1. 单元测试,最好全过程采用TDD(测试驱动开发) 

这样才能让人有信心修改你的代码。

2. 参考业内成熟实践与设计模式

这个事情,要多讲一句,千万不能过头。为了追求可扩展性,可重用性,甚至仅仅是为了玩弄设计模式,会让一个项目成为过度设计的牺牲品,千万不能过头。

3. 定期重构

一上来就向设计模式靠拢是很危险的,重构时以设计模式为参考会好一些。但是,大多时候,我们没时间重构。。。

所以,还是TDD最实在,按照TDD的工作模式,你的项目几乎每天都有大大小小的重构。

4. 结对编程

这个@李楠 已经提到了。让知识在团队中不只是一个人掌握,很重要。

大概就是这些吧。。。

 

简评@aimingoo 的《第三种“没信仰”》

周爱民兄(他居然称我为庄兄,他明明比我大啊),昨天写了一篇blog《第三种“没信仰”》,在回应我以前的一篇《我的信仰地图》之外,说了很多有意思的观点。

我今天细细读了一遍,打算好好回复一篇。

但是,这样的文章要回复起来,很不容易,我只能剑走偏逢,另外引一段话来“撑腰”:

“故法华经云:佛自住大乘,如其所得法,定慧力庄严,以此度众生。当知此之二法如车之双轮鸟之两翼。若偏修习即堕邪倒。故经云。若偏修禅定福德。不学智慧。名之曰愚。偏学智慧不修禅定福德名之曰狂。狂愚之过虽小不同。邪见轮转盖无差别。若不均等此则行乖圆备。何能疾登极果。”

这一段是我最近正在看的《童蒙止观》里,智者大师引经据典的一段话。

这段话,看得我悚然而惊,为什么?因为很长一段时间,我进庙磕头求佛求菩萨,一直只求智慧增长,别无他求。因为,我当时的理解是:只要有智慧,其他都会有的。现在看来,也是邪见的一种啊。

爱民兄的文章主旨,如果我没有理解错的话,“在我目前这个状态下,我没有信仰的需求。科学、哲学、宗教里那些有用的部分,我都已经理解了。”

有一句俗话叫:“书到用时方恨少”。那些你觉得已经理解的道理,当你需要的时候,才会恨自己“没有真正掌握”啊。

所以,在我看来,爱民兄这种“没信仰”的选择,恰恰是智者大师所说的“狂”的一种,相当的危险。因为跟你很熟,也就不客气的在这里说了,万望海涵。。。

说到真修实证,我也完全没有经验,只是发心打算开始修起来,微博上的@张峰的心斋堂说到:“老庄,其实佛道中有很大一块关于实证实修的部分,倒是与科学研究类似。你实修证到了,自然就会信,比如说马相藏阴。但这一部分各家都秘笈自珍,还加入各种隐语,导致很难从公开渠道获得加以验证,不然倒是很好的科研素材”

我很期待他能够多介绍一些实证、实修方面的材料。

我对“知行合一”的理解

知乎上有一个问题:为什么有很多道理我们知道、也认可,但就是做不到?从知道到做到之间有什么被我们忽视的重要东西?

我收藏了很久,但是一直在心里打腹稿,没有想好怎么回答。今天写了一篇blog,来试着梳理一下自己对“知行合一”的理解。

2007年,我写过一篇博客,叫做《儒家的那些道理》,摘抄一段过来:

———————————————引用开始————————————————
举 一个佛家的禅宗故事来说明吧。当年达摩西来,经过神光法师讲经处,发现这个神光法师辩才无碍,讲起佛经来,天花乱坠,地涌金莲。结果呢,一旦知道 死期将近,照样惶惶不安,恐惧不已。到头来还是跑去求达摩祖师帮他安心。为什么呢?因为佛家的道理固然人人讲得,佛家的境界,未必人人都能达成。道理讲得 再好,也不过口头禅而已。等到神光改名慧可,在达摩面前九年长跪不起,以至于自断一臂,只求安心,达摩祖师说:“将心来与汝安。”慧可沉默良久,然后才 说:“觅心了不可得。”达摩祖师说:“我与汝安心竟。”于是慧可当下大悟,成为禅宗二祖。但是,这一句“觅心了不可得”的道理,你我都读在眼里,怎么你我 都还是没有开悟呢?

无论是佛家的道理,还是儒家的道理,一字一句的背下来,是没有用的。非得要能够将那些道理,真正化入自己的生命,那才是自己真正得到了!这些永不会失落的财富,才是真正宝贵的财富。
———————————————引用结束————————————————

但是,在我的那篇文章里,根本没有讲:“如何将道理,真正化入自己的生命。”因为,我自己也不知道。

 

到了2009年的时候,我写了另外一篇博客,叫做《<Lie to me>、<三体-黑暗森林>以及知行合一》,也摘抄一段过来:

———————————————引用开始————————————————
我最近在写的一个稿子,其中有这么一段:

一 直有这样一种感觉,技术方面的东西,往往是“知难行易”。理解起来很困难,一旦理解了,其实很容易做到。而管理方面的东西,却往往是“知易行 难”,都是些常识性的东西,但是要坚持做到,却非常的困难。不过,后来读到了一些有关王阳明的“知行合一”的理论。似乎在他看来,如果是行得不够好,那就 肯定是知得不够深。而且,要知得够深,也一定是不能脱离行的。想来也的确有道理,但是也还远没有参透。

昨天晚上在想着《Lie to me》和表情识别的事情,突然心有所悟。《Lie to me》中一个非常重要的概念,叫做微表情。他的理论基础是:人类在无意识中泄露出来的表情,可能转瞬即逝,却表达了无法掩饰的内心世界。更多介绍连接

但是,大多数人,却无法察觉到微表情。因为短短1/10秒的面部表情变化,没有经过专业训练的人,是根本无法察觉的。
……
Cal Lightman博士经过长期艰苦的研究与自我训练,才掌握了识别1/10秒微表情的能力,这既是知的成长,又是行的成长。知与行,是不可分割的。从这个角度来看,我对知行合一的理解,又深了一层了。
———————————————引用结束————————————————

说实话,这个只是我自己在瞎参悟,因为一直还没有读过王阳明的《传习录》原文。

 

今天,我总算仔仔细细的读了一遍王阳明讲知行合一的段落,特摘录如下:

———————————————引用开始————————————————
爱 因未会先生“知行合一”之训,与宗贤、惟贤往复辩论,未能决,以问于先生。

先生曰:“试举看。”

爱曰:“如今人尽有知得父当孝、兄当弟者,却不能孝、不 能弟,便是知与行分明是两件。”

先生曰:“此已被私欲隔断,不是知行的本体了。未有知而不行者。知而不行,只是未知。圣贤教人知行,正是安复那本体,不是 着你只恁的便罢。故《大学》指个真知行与人看,说‘如好好色,如恶恶臭’。见好色属知,好好色属行。只见那好色时已自好了,不是见了后又立个心去好。闻恶 臭属知,恶恶臭属行。只闻那恶臭时已自恶了,不是闻了后别立个心去恶。如鼻塞人虽见恶臭在前,鼻中不曾闻得,便亦不甚恶,亦只是不曾知臭。就如称某人知 孝、某人知弟,必是其人已曾行孝行弟,方可称他知孝知弟,不成只是晓得说些孝弟的话,便可称为知孝弟。又如知痛,必已自痛了方知痛,知寒,必已自寒了;知 饥,必已自饥了;知行如何分得开?此便是知行的本体,不曾有私意隔断的。圣人教人,必要是如此,方可谓之知,不然,只是不曾知。此却是何等紧切着实的工 夫!如今苦苦定要说知行做两个,是甚么意?某要说做一个是甚么意?若不知立言宗旨,只管说一个两个,亦有甚用?”

爱曰:“古人说知行做两个,亦是要人见个 分晓,一行做知的功夫,一行做行的功夫,即功夫始有下落。”

先生曰:“此却失了古人宗旨也。某尝说知是行的主意,行是知的功夫;知是行之始,行是知之成。 若会得时,只说一个知已自有行在,只说一个行已自有知在。古人所以既说一个知又说一个行者,只为世间有一种人,懵懵懂懂的任意去做,全不解思维省察,也只 是个冥行妄作,所以必说个知,方才行得是;又有一种人,茫茫荡荡悬空去思索,全不肯着实躬行,也只是个揣摸影响,所以必说一个行,方才知得真。此是古人不 得已补偏救弊的说话,若见得这个意时,即一言而足,今人却就将知行分作两件去做,以为必先知了然后能行,我如今且去讲习讨论做知的工夫,待知得真了方去做 行的工夫,故遂终身不行,亦遂终身不知。此不是小病痛,其来已非一日矣。某今说个知行合一,正是对病的药。又不是某凿空杜撰,知行本体原是如此。今若知得 宗旨时,即说两个亦不妨,亦只是一个;若不会宗旨,便说一个,亦济得甚事?只是闲说话。”
———————————————引用结束————————————————

简单的说,我的理解如下:

1. 知一分,则能行一分。行不出来的,就不算真知道。

2. 儒家讲吾日三省吾身,就是每日反省:行不到的地方,知见有何不足。今后如果要行,该如何去行,既要在道理上想透彻,又要不断在事上磨练。

3. 中国传统文化,儒释道三家,都讲功夫,修身/修行/修炼。都是在探究,如何将那些道理,真正化入自己的生命。

4. 前两天,我在微博上写到:想通了一件大事,也定下了今年的努力目标:知行合一,不忘初心,尽心竭力,诚以笃行。

要创业,就别听VC的!

零、缘起

今天在微博看到一条@薛蛮子 的段子,看得我相当火大,终于下决心写这篇博客,好好谈谈我对VC的鄙视。

商业计划书是个非常重要的东西,主要的原因看你是不是较劲吐出来,所有伟大的事业都是最简单的事业,微软做Windows的,腾讯是QQ,李彦宏是搜索,一句话就搞定了,你只要想清楚,这件事只有想的清才是做的清,凡是一大堆屁话一看就是不靠谱的。

薛蛮子这段话里,有多少不靠谱的槽点呢?咱们慢慢来说:

1、微软不只是做Windows的,他还做DOS,Office,XBOX……当初微软刚刚成立的时候,他的主营业务是BASIC解释器,估计薛蛮子都没听说过什么叫BASIC。

2、腾讯倒是一直在做QQ,但是1998年成立时,他们主要业务是为寻呼台建立网上寻呼系统。最落魄的时候,马化腾差点卖掉腾讯,直到2000年,QQ里面才加入了广告。开始有了收入。

3、百度的确是做搜索,但是真正让百度赚钱的,是广告与竞价排名。

这些事情,我还是说得太简单,因为事实上,一句话根本是说不清楚的。

一、为什么VC的眼光往往不靠谱?

所谓风险投资,就是高风险,高收益的投资。高风险,就是失败率极高的投资。十次投资有一次成功,VC就能够赚钱,甚至能够大大超过另外九次的亏损。因此,我们看到那些风光无限的投资人,在台前活跃,就认为他们的眼光独到。当然,他们只会大力宣传自己成功的那几次。

一个看十次有九次看错的人,通过大力宣传自己唯一成功的那一次,让人们相信自己常常是正确的。而那些被洗脑的家伙,居然就相信他们了,居然就崇拜他们了,居然就信奉他们了,居然就以他们为马首是瞻了~~~

二、为什么VC的选择通常是错误的?

所谓风险投资,并非投资成功的企业,而是投资最容易获得高回报的企业。所以,你常常会看到业界不断的会有各种投资热点,投资动向,那些东西,会有一堆的VC冲上去,哭着喊着的要投资,要把钱给人家。为什么?不是因为那个团队,那个项目真的有可能成功,而是概念一旦热门,就有机会,在短期内炒热,然后转手高价套现。

所以,原来是VC跟随潮流投资,现在他们更加强大,简直可以先制造潮流,然后忽悠创业团队跟着他们走了。

三、为什么VC的判断常常是急功近利的?

任何投资,最大的两忌是恐惧与贪婪。而作为风险与回报最高的风险投资,VC们在所有的投资者中,是最为贪婪的。而在可能的失败到来时,又是最为恐惧的。巨大的贪婪与巨大的恐惧,都会扭曲一个人的判断,而在这个世界上的VC,都是在贪婪与恐惧中不断摇摆的家伙。他们的急功近利,几乎是必然的。

四、创业团队应该如何与VC相处?

首先,创业团队不要为了VC而创业,因为拿到风投,仅仅是事业的开始,而非事业的成功。无数拿到了风投的创业团队,在N年以后破产倒闭,回想当年的风光,也不过是些幻觉而已。

其次,创业团队不要为了VC的建议而动摇,VC只是出钱的人,甚至不能算是业内人士,他们的建议,未必是为了你事业的长远发展,也许也许只是为了他能够更快脱手。

最后,真正牛逼的创业团队,根本不需要去给VC解释自己的事业,VC会帮你解释,会帮你想理由,会帮你做宣传,会讨好你,会恳求你,求你拿他的钱。因为:你的成功是如此的显而易见,根本不需要他们来认同。接受他们的投资,可以说是带他们发财。VC不是你的恩人,只是你的事业合作伙伴而已。所谓感恩,你可以对事业上的每一个合作伙伴,同样的感恩。

五、结论

以前赵本山有一个广告,是卖药的。大意是:选药啊,你别看广告,要看疗效!

我认为这个广告非常独特,因为他相当的反其道而行之。

同样的,创业的时候,你别听VC的。如果一定要听,你听用户的!

 

补充:

1、对了,还有一个槽忘记吐了:有一种傻VC,还喜欢问一个问题,你的商业模式如果被腾讯抄袭了怎么办?一个推荐的回答是:滚!

2、@安普若-安校长 推荐的两篇文章,值得一读:《与投资人接触时常犯的十大错误》《VC系列:一个工程师眼中的风险投资家