如何读代码1 - 驳斥两条常见误区
Tactoth
首先我必须有力的反击在软件开发中充满迷惑性的两点误区，据我所知者两点误区已经深深毒害了软件开发人员多年，大大的降低了代码质量。他们是：
1. 我们的代码应该有很多文档。
2. 我们的代码似乎很烂。
首先来看看误区1：
在软件开发中，新加入一个项目的程序员常常会有这样的抱怨： “我们的代码没有文档”。这种抱怨甚至会得到项目中已经颇有经验的程序员的附和。但其实这
种抱怨是带有不合理要求的，不应该支持的，是可以驳回的。
首先，这世界上90+的软件是没有(或缺乏)文档的，千万不要以为在大公司会有很“理想”的写一大堆文档然后才开始写代码的“正规流程”。如果不相信，
可以问问你在大公司，比如Microsoft, IBM等工作的朋友，看看我们耳熟能详的那些软件到底有多少文档。似乎只有外包公司比较重视文档，然而
敏捷开发的风行也使开发者对书写笨重的文档难以保持耐心。文档与代码的不同步也使许多文档变得失去意义。
其次，让我们来看看文档对于开发者的意义。也许新加入的项目组成员会想，在理想的情况下，只要让我先看看文档，一点代码都不用看。等我通读完文档后，我
打开代码就懂得全部的代码啦！然而这真的很幼稚。
好吧，也许你理由还是很充分，你认为磨刀不误砍柴工，你认为…. ， 总之你认为就是应该有文档嘛！但是我们得面对现实的对不对，现实是，你所拥有的只
是一堆代码，放在一个Visual Studio的Solution文件里面，你无法使用心爱的Adobe Reader, Microsoft
PowerPoint and Visio，你只能使用对着Visual Studio，阅读一行行代码，所以，你所能考虑的只应该是如何多快好省的搞
懂这些代码。
当然，我不是说你应该不写文档。
误区二：
好吧，无论有没有文档，有一件事情是肯定的，你现在对代码有了一些了解。是时候发表点自己的评价了，于是你说：
“我们的代码烂到家了！”
你的评价是有道理的，因为你的评价基于你对软件开发的真知灼见。你举出了无可动摇的事实，你说：
“这个地方应该用State模式，而我们则使用了大量的 if, else, switch。这个函数纯粹就是一个万能函数，并且与
另一个函数严重耦合，更糟的是函数名也挂羊头卖狗肉。这个地方应该用二分查找，这里则应该用动态规划提高效率…”总之：
“这代码真应该从一开始就让我写！”
好主意！如果一开始就让你写，或许你会理解所有代码的来龙去脉，你会认为代码本来就应该是这个样子。你会认识到我们为得到这些混乱的
代码，所付出的巨大努力：一个个优秀的程序员，一个个目光犀利的QA，以及大量花数年时间使用我们软件的客户，如辛勤哺育孩子一般，让我们的软件逐渐成
长起来，而有人却认为他很烂？！
现在让我们看看我们的代码，看看这个5000行以上的函数，里面署有50位程序员的大名。而他的功能仅仅是显示一个窗口，随着岁月的
积累，他开始变得庞大。但是不像中年发福的人，这个函数的增长，是在积累有用的东西，那就是：Bug fix。有人发现在没有安装Internet
Explorer时窗口不能正确的现实，有人为内存不足时正确的现实窗口做了点特殊处理，为了使某个将数据存储与局域网服务器的客户能看到给窗口，我们
还得加点代码；至于丑陋的LoadLibrary的调用，则是为了支持Windows 98以及Linux用户。
所有这些bug的发现都是在我们的软件被大量使用 - 测试之后发现的，定位这些bug花了我们大量的精力，时间。在一个个
Bugfix 中，我们的软件从一个婴儿 – 单纯，简洁，变得越来越成熟，稳定，越来越善于处理来自客户的需求。然而，随着一个个Bug被修掉，我们
的代码会逐渐零乱，代码中或许会混杂着各种各样的风格，或许会有重复的API调用，或许有些地方必须要提高性能了，甚至或许会有自相矛盾的地方。但是你
应该感觉得到与这微不足道的缺陷相比，他所能提供的强大的功能，他所具有的巨大的容错性，才是我们代码真正的本色！
至于那些毛病，我们有你，优秀的开发人员。对于软件进化已成为软件开发主流的当代，代码重构是一个程序员最需要提高的能力。
况且，从态度来说，一个喜欢自己工作与之上的code base的程序员，会有更积极的态度，因而也更能改进现有的代码。
敬请期待续篇...
halida
不然二次开发的成本和风险很高,维护也相当困难.
就算什么文档都没有,至少要有:1设计文档 2代码注释
2代码是会随时间成长变乱的,我同意.
就我而言,代码再乱,只要不需要修改,我就会把他们包起来,成为一个API,再也不会管他们.这样眼不见心静.代码乱是可以,但是架构一定要清晰.代码
是给人看的,编译出来的东西才是给机器执行的.
但是会遇到这样的情况:代码很乱,还需要修改,这个时候就要做重构和测试.
On Feb 11, 9:56 pm, Tactoth <tact...@gmail.com> wrote:
> 大家好，这是我的第一帖，这篇文章开头是写完在我的同事中交流的，后来有同事建议贴到这里来，说是比较适合讨论，希望能抛砖引玉。
>
> 首先我必须有力的反击在软件开发中充满迷惑性的两点误区，据我所知者两点误区已经深深毒害了软件开发人员多年，大大的降低了代码质量。他们是：
>
> 1. 我们的代码应该有很多文档。
>
> 2. 我们的代码似乎很烂。
>
> 首先来看看误区1：
>
> 在软件开发中，新加入一个项目的程序员常常会有这样的抱怨： "我们的代码没有文档"。这种抱怨甚至会得到项目中已经颇有经验的程序员的附和。但其实这
> 种抱怨是带有不合理要求的，不应该支持的，是可以驳回的。
>
> 首先，这世界上90+的软件是没有(或缺乏)文档的，千万不要以为在大公司会有很"理想"的写一大堆文档然后才开始写代码的"正规流程"。如果不相信，
> 可以问问你在大公司，比如Microsoft, IBM等工作的朋友，看看我们耳熟能详的那些软件到底有多少文档。似乎只有外包公司比较重视文档，然而
> 敏捷开发的风行也使开发者对书写笨重的文档难以保持耐心。文档与代码的不同步也使许多文档变得失去意义。
>
> 其次，让我们来看看文档对于开发者的意义。也许新加入的项目组成员会想，在理想的情况下，只要让我先看看文档，一点代码都不用看。等我通读完文档后，我
> 打开代码就懂得全部的代码啦！然而这真的很幼稚。
>
> 好吧，也许你理由还是很充分，你认为磨刀不误砍柴工，你认为.... ， 总之你认为就是应该有文档嘛！但是我们得面对现实的对不对，现实是，你所拥有的只
> 是一堆代码，放在一个Visual Studio的Solution文件里面，你无法使用心爱的Adobe Reader, Microsoft
> PowerPoint and Visio，你只能使用对着Visual Studio，阅读一行行代码，所以，你所能考虑的只应该是如何多快好省的搞
> 懂这些代码。
>
> 当然，我不是说你应该不写文档。
>
> 误区二：
>
> 好吧，无论有没有文档，有一件事情是肯定的，你现在对代码有了一些了解。是时候发表点自己的评价了，于是你说：
>
> "我们的代码烂到家了！"
>
> 你的评价是有道理的，因为你的评价基于你对软件开发的真知灼见。你举出了无可动摇的事实，你说：
>
> "这个地方应该用State模式，而我们则使用了大量的 if, else, switch。这个函数纯粹就是一个万能函数，并且与
> 另一个函数严重耦合，更糟的是函数名也挂羊头卖狗肉。这个地方应该用二分查找，这里则应该用动态规划提高效率..."总之：
>
> "这代码真应该从一开始就让我写！"
>
> 好主意！如果一开始就让你写，或许你会理解所有代码的来龙去脉，你会认为代码本来就应该是这个样子。你会认识到我们为得到这些混乱的
> 代码，所付出的巨大努力：一个个优秀的程序员，一个个目光犀利的QA，以及大量花数年时间使用我们软件的客户，如辛勤哺育孩子一般，让我们的软件逐渐成
> 长起来，而有人却认为他很烂？！
>
> 现在让我们看看我们的代码，看看这个5000行以上的函数，里面署有50位程序员的大名。而他的功能仅仅是显示一个窗口，随着岁月的
> 积累，他开始变得庞大。但是不像中年发福的人，这个函数的增长，是在积累有用的东西，那就是：Bug fix。有人发现在没有安装Internet
> Explorer时窗口不能正确的现实，有人为内存不足时正确的现实窗口做了点特殊处理，为了使某个将数据存储与局域网服务器的客户能看到给窗口，我们
> 还得加点代码；至于丑陋的LoadLibrary的调用，则是为了支持Windows 98以及Linux用户。
>
> 所有这些bug的发现都是在我们的软件被大量使用 - 测试之后发现的，定位这些bug花了我们大量的精力，时间。在一个个
> Bugfix 中，我们的软件从一个婴儿 - 单纯，简洁，变得越来越成熟，稳定，越来越善于处理来自客户的需求。然而，随着一个个Bug被修掉，我们
LeeoNix
就第二条，我就我看到的一些乱的代码。有时候就是不堪忍受的，尽管他们看上去
很好。
1、5000行的函数，怎么不直接写汇编呢？这个还好意思说的出口？重构的Extract
Method就是来解决这个的。
2、就你所说的在代码里有50个人的modified抑或bug fixed类似的署名，那简直就
是不能容忍的一件事情，你是在写代码呢？还是写注释呢？还是来声明你对你修改
的东西负责？
接手的人应该马上用版本控制软件来替换。把他的修改地方文档化。如果这样的事
情还好意思说的出口，那我持绝对的反对态度。
最后：我还是没明白你说的这些话。代码如果像意大利面条一样的一团浆糊，那就
赶快去重构他。而不是炫耀一样的说：
“我们的软件从一个婴儿 – 单纯，简洁，变得越来越成熟，稳定，越来越善于处理来自客户的需求。”
这样你的婴儿只能长大为一个畸形儿！！！
__________________________________________________________________
LeeoNix
Tactoth 写道:
DaiZW
我理想中的状态是: 文档能够清晰表达软件的工作流程, 不过不会详细到微小的代码改动也必须修改对应的文档; 软件工作的细节部分应该在代码注释中得到体现, 就是说详细的注释是必要的.
2. 我们的代码似乎很烂。
"现在让我们看看我们的代码，看看这个5000行以上的函数，
里面署有50位程序员的大名。而他的功能仅仅是显示一个窗口"
不要说读, 单是想想"5000行以上的函数"都觉得是在自虐.
还有"里面署有50位程序员的大名". 如果这个工程使用版本控制系统的话,
我不知道为什么还有署名的必要, 有那功夫你多写点注释(比如改了哪里, 为什么改)不好吗?
如果一份代码里我没看到多少注释, 却看到数不清的程序员的名字,
我会说: 谁修改的, who the hell cares!
OVER
sagasw
文档或者代码，个人有个人的想法，
但是对于代码而言不是旧的就是好的，而且长函数肯定是不行的。
文档，我个人建议是少写，尽量放在代码中，或者代码清晰到一看就知道。
Hua Zhen
大家好，这是我的第一帖，这篇文章开头是写完在我的同事中交流的，后来有同事建议贴到这里来，说是比较适合讨论，希望能抛砖引玉。
首先我必须有力的反击在软件开发中充满迷惑性的两点误区，据我所知者两点误区已经深深毒害了软件开发人员多年，大大的降低了代码质量。他们是：
这两点，个人感觉应该是个"度"的问题。先抛开这个不论，楼主的解释只是在说这"两点误区"不对，从中我却没有看出抱有这种想法如何会 "大大的降低了代码质量" ？
1. 我们的代码应该有很多文档。
2. 我们的代码似乎很烂。
如果是产品开发，"很多文档"是不必要，个人认为没有维护可能的文档是不必要的。但是恰当的文档积累，应该会让这个团队更加成熟，让新员工能更快上手，让老员工的跳槽带来的震荡变小。
因此，我觉得讨论文档该多还是该少没多大意义，值得讨论的，应该是（在具体的环境下）哪些文档是必须的，哪些是不必要的。以及，对于这些必须的文档，如何更好的维护。
至于代码烂不烂的问题，我重构做的不多，就不敢发表意见了。
--
凡事包容，凡事相信，凡事盼望，凡事忍耐。
LeeoNix
优点。
我以前也随着公司的一些人，学了书写bug fix注释的坏毛病。也有写大函数的坏
毛病。
自从我加入一个开源项目之后，领导项目的老兄耐心的给我讲解了为什么要有版本
控制系统，而且写Bug fix注释为什么是一种坏习惯。
所以，如果我所在的公司不提供版本控制，我就会自己架设一个。如果离职，把仓
库直接交出去就可以了。
为什么进行重构？尽管那时候我还不知道重构这个概念。通过他的推荐我买了《重
构》这本书。
我到现在都十分感谢这位亦师亦友的朋友，对我的指点，我一辈子感激。
5000行的大函数，如果一开始编写的人头脑里有结构化设计的概念，绝对不会写出
这么一个玩意儿。
如果有结构化设计概念的人，拿过来第一件事，最好是把这个大喊数重构掉。
不单单为自己服务，也为以后拿到这些个代码的人服务。
可以毫不客气的说，此前那50个书写bug fix的人，很是不负责任，这样会把一份
代码弄得越来越乱。
嗯，我的反对态度很强烈，敬请请谅解。
__________________________________________________________________
LeeoNix
Tactoth 写道:
laihj
结果并不是成熟稳定，而是一个可以完成功能的不知名怪物，如果程序继续运行维护，总有一天会变成弗兰肯斯坦的
LeeoNix
>“这个地方应该用State模式，而我们则使用了大量的 if, else, switch。这个函数纯粹就是一个万能函数，并且与
>另一个函数严重耦合，更糟的是函数名也挂羊头卖狗肉。这个地方应该用二分查找，这里则应该用动态规划提高效率…”
这个看上去就是技术狂人的抱怨。但你怎么不耐心看看这句话呢？
“if, else, switch。这个函数纯粹就是一个万能函数”，有时候就是需要一个超级大的开关。我也干过，这个你可以解释。
“并且与另一个函数严重耦合”。为什么耦合？耦合程度如何？为什么造成了严重耦合？何不问问自己问问别人？自己是不是真的做错了？
“更糟的是函数名也挂羊头卖狗肉”，你可以不反驳他，可以说：“既然你提了？那该起个什么名字呢？”你说句软话，气氛不就不紧张了？毕竟交流不是吵架。
如果说这样话的同事，你耐心听取他的话，然后顺着他的话去延续做下去。
这样的沟通交流为什么不耐心继续下去呢？难道这句话就没有一点可取之处？
像你这样的口气最后肯定就是公说公有理婆说婆有理的情况，然后就是各执一词的争论而不是互相吸取经验教训。
>以及大量花数年时间使用我们软件的客户，如辛勤哺育孩子一般，让我们的软件逐渐成长起来，而有人却认为他很烂？！
而你这句话更像一个超级大的抱怨。潜台词好像，我干了这么多活，你一点都没有干，就在这里挑三拣四的批评我们干的事情。而且说的很恶心，用了“很烂”这个词。
我在TopLanguage的签名就是：如果你没有被批评过的话，那证明你没有做过多少事儿。
唉，谁都有“护犊子”的心态。谁都不想看到别人对自己的东西说三道四的。我承认，你说的这几句话别人评论的话，其态度非常尖锐。
我问一下：你是不是为了抱怨这么一句话而发出这样的一篇文章？
那我建议你，耐心的反思一下自己的问题到底在哪里。
__________________________________________________________________
LeeoNix
Tactoth 写道:
Iceberg
坏习惯"，就领会不了其中精要。我google了"bugfix注释 坏习惯"，没发现什么有用的信息。能否请LeeoNix再展开说明一下？
我先抛砖引玉。仅就我的个人习惯来说，我fix了一些比较隐蔽但又是琐碎的BUG时，我是会举手之劳地在代码后写上一句简单说明。我的出发点是，"既然
这个地方曾经疏忽出过错，那么事实证实这个陷阱是很隐蔽的，我在旁边留个小纸条让后来人小心，是值得的"。将来重构这段代码的人如果看到这个注释，就会
加以注意，不犯同样的错误。
一下子比较难举出实际的例子。这里我勉强找到一个。假设有个函数要接收一个文件路径进行处理：
do_something(filepath)
一般来说，输入的filepath是一个纯文件名或者含相对路径或者含绝对路径，do_something()及其内部调用的底层open()函数都能
够正常工作，所以也就对输入参数的形式没有明确要求。直到有一天，我们发现在某种特殊情况下，成品可执行程序的运行时目录会改变，这时，使用纯文件名或
者含相对路径的输入都会出错。在这种情况下，本来有条件的话直接改do_something()内部，在一开始就强制把输入参数转换成绝对路径，可能是
最好的解决方法，但如果do_something()是来自于某个底层开发包，我们无法或不便修改它的源码，那么我就会把调用do_something
()的那一行改为：
do_something(abspath(filepath)) //一定要使用绝对路径，否则在xxxx场合会无法确定实际要操作的文件名
如果没有后面的注释，可能重构时就把这个bugfix遗失了。
当然了，我强调一点，注释应该写真正有意义的内容。而如果仅仅是写上自己的名字，除了炫耀"某某至此一游"之外，一点用都没有。
> > 好吧，也许你理由还是很充分，你认为磨刀不误砍柴工，你认为.... ， 总之你认为就是应该有文档嘛！但是我们得面对现实的对不对，现实是，你所拥有的只
> > 是一堆代码，放在一个Visual Studio的Solution文件里面，你无法使用心爱的Adobe Reader, Microsoft
> > PowerPoint and Visio，你只能使用对着Visual Studio，阅读一行行代码，所以，你所能考虑的只应该是如何多快好省的搞
> > 懂这些代码。
>
> > 当然，我不是说你应该不写文档。
>
> > 误区二：
>
> > 好吧，无论有没有文档，有一件事情是肯定的，你现在对代码有了一些了解。是时候发表点自己的评价了，于是你说：
>
> > "我们的代码烂到家了！"
>
> > 你的评价是有道理的，因为你的评价基于你对软件开发的真知灼见。你举出了无可动摇的事实，你说：
>
> > "这个地方应该用State模式，而我们则使用了大量的 if, else, switch。这个函数纯粹就是一个万能函数，并且与
> > 另一个函数严重耦合，更糟的是函数名也挂羊头卖狗肉。这个地方应该用二分查找，这里则应该用动态规划提高效率..."总之：
>
> > "这代码真应该从一开始就让我写！"
>
> > 好主意！如果一开始就让你写，或许你会理解所有代码的来龙去脉，你会认为代码本来就应该是这个样子。你会认识到我们为得到这些混乱的
> > 代码，所付出的巨大努力：一个个优秀的程序员，一个个目光犀利的QA，以及大量花数年时间使用我们软件的客户，如辛勤哺育孩子一般，让我们的软件逐渐成
> > 长起来，而有人却认为他很烂？！
>
> > 现在让我们看看我们的代码，看看这个5000行以上的函数，里面署有50位程序员的大名。而他的功能仅仅是显示一个窗口，随着岁月的
> > 积累，他开始变得庞大。但是不像中年发福的人，这个函数的增长，是在积累有用的东西，那就是：Bug fix。有人发现在没有安装Internet
> > Explorer时窗口不能正确的现实，有人为内存不足时正确的现实窗口做了点特殊处理，为了使某个将数据存储与局域网服务器的客户能看到给窗口，我们
> > 还得加点代码；至于丑陋的LoadLibrary的调用，则是为了支持Windows 98以及Linux用户。
>
> > 所有这些bug的发现都是在我们的软件被大量使用 - 测试之后发现的，定位这些bug花了我们大量的精力，时间。在一个个
> > Bugfix 中，我们的软件从一个婴儿 - 单纯，简洁，变得越来越成熟，稳定，越来越善于处理来自客户的需求。然而，随着一个个Bug被修掉，我们
Zhang Chiyuan
一直习惯把 bug fix 相关信息写在版本控制的 log 里，但是后来有一次程序出了问题，后来发现这个问题其实我 fix 过，
不过 fix 的那个语句乍一看似乎是没什么用处的，被另一个开发人员在重构的时候给去掉了，导致了这样的问题。当然
回归测试可以从一定程度上避免这种问题，但是并不是所有的行为都可以用自动测试来完成的。
--
pluskid
LeeoNix
的功能注释，对修改的解释。
我说的是一些人。就是这么写类似：modified by leeonix。或者 bug fixed by
leeonix 这样的。一点内容都没有只是说明谁在里面修改的。
btw：我现在接手的一些2002年的C++代码，里面就有很大量的这样注释。有的甚至
这样写：
//-----begin modify-----
代码。
//-----end modify-----
//modified by leeonix
类似这样的代码。
呵呵，不用惊奇，就是存在这样的代码，在2001~2003年差不多这段时间，很多人
都在写这样的代码。
另外一种就是把旧代码注释掉，然后写一行注释说明放弃这行代码，然后添加：
modified by leeonix之类的话。类似：
//do_something() 这些代码放弃
替代代码。
如果带着50个甚至更多这样的，你会不会感觉很恐怖呢？
嗯。这个就是版本控制+Bug跟踪系统所解决的问题。
我这样的说明你是否满意呢？
__________________________________________________________________
LeeoNix
Iceberg 写道:
DQP
我在google上搜bug fix注释 和 bug fix comment都没有找到相关的解释
谢谢 ：）
On 2月12日, 上午9时28分, LeeoNix <leeoni...@gmail.com> wrote:
> > 好吧，也许你理由还是很充分，你认为磨刀不误砍柴工，你认为.... ， 总之你认为就是应该有文档嘛！但是我们得面对现实的对不对，现实是，你所拥有的只
> > 是一堆代码，放在一个Visual Studio的Solution文件里面，你无法使用心爱的Adobe Reader, Microsoft
> > PowerPoint and Visio，你只能使用对着Visual Studio，阅读一行行代码，所以，你所能考虑的只应该是如何多快好省的搞
> > 懂这些代码。
>
> > 当然，我不是说你应该不写文档。
>
> > 误区二：
>
> > 好吧，无论有没有文档，有一件事情是肯定的，你现在对代码有了一些了解。是时候发表点自己的评价了，于是你说：
>
> > "我们的代码烂到家了！"
>
> > 你的评价是有道理的，因为你的评价基于你对软件开发的真知灼见。你举出了无可动摇的事实，你说：
>
> > "这个地方应该用State模式，而我们则使用了大量的 if, else, switch。这个函数纯粹就是一个万能函数，并且与
> > 另一个函数严重耦合，更糟的是函数名也挂羊头卖狗肉。这个地方应该用二分查找，这里则应该用动态规划提高效率..."总之：
>
> > "这代码真应该从一开始就让我写！"
>
> > 好主意！如果一开始就让你写，或许你会理解所有代码的来龙去脉，你会认为代码本来就应该是这个样子。你会认识到我们为得到这些混乱的
> > 代码，所付出的巨大努力：一个个优秀的程序员，一个个目光犀利的QA，以及大量花数年时间使用我们软件的客户，如辛勤哺育孩子一般，让我们的软件逐渐成
> > 长起来，而有人却认为他很烂？！
>
> > 现在让我们看看我们的代码，看看这个5000行以上的函数，里面署有50位程序员的大名。而他的功能仅仅是显示一个窗口，随着岁月的
> > 积累，他开始变得庞大。但是不像中年发福的人，这个函数的增长，是在积累有用的东西，那就是：Bug fix。有人发现在没有安装Internet
> > Explorer时窗口不能正确的现实，有人为内存不足时正确的现实窗口做了点特殊处理，为了使某个将数据存储与局域网服务器的客户能看到给窗口，我们
> > 还得加点代码；至于丑陋的LoadLibrary的调用，则是为了支持Windows 98以及Linux用户。
>
> > 所有这些bug的发现都是在我们的软件被大量使用 - 测试之后发现的，定位这些bug花了我们大量的精力，时间。在一个个
> > Bugfix 中，我们的软件从一个婴儿 - 单纯，简洁，变得越来越成熟，稳定，越来越善于处理来自客户的需求。然而，随着一个个Bug被修掉，我们
LeeoNix
其实有的地方还是特殊情况，比如特殊的地方，
有的时候会把一些修改的历史用注释的形式写在修改的代码附近，以便后来修改的
人不会犯同样的错误。
比如我参与的开源软件的代码里，就有好几个地方对写明为什么字符串不能本地化
的说明。这个特殊情况特殊处理。
__________________________________________________________________
LeeoNix
Zhang Chiyuan 写道:
> 我也觉得许多时候 bugfix 的注释还是必要的，特别是一些看起来比较奇怪的
> workaround ，我就有过一次经历，以前也
> 一直习惯把 bug fix 相关信息写在版本控制的 log 里，但是后来有一次程序出
> 了问题，后来发现这个问题其实我 fix 过，
> 不过 fix 的那个语句乍一看似乎是没什么用处的，被另一个开发人员在重构的
> 时候给去掉了，导致了这样的问题。当然
> 回归测试可以从一定程度上避免这种问题，但是并不是所有的行为都可以用自动
> 测试来完成的。
>
> 2009/2/12 Iceberg <ice...@21cn.com <mailto:ice...@21cn.com>>
>
> LeeoNix 说的绝大部分内容，例如版本控制、重构、结构化设计、不写长函
Stanley Xu
1. 一个bug发现，那么应该有一个对应的新的testcase，别人不需要考虑你是怎么解决的，也不用知道多隐蔽，test case跑不过说明一切
2. 如果是真正意义上的fix，那么功能没有改变，所谓的fix的信息可以放在SCM里，放在代码注释里属于扰乱视听
3. 如果是个work around，倒是合适在代码里加个新的TODO
Best wishes,
Stanley Xu
Tactoth
所以这篇文章毫无感情色彩，只是我对软件开发的一点小小看法。至于这种稍微夸张的写法，实在是我写作的习惯 :)。
On 2月12日, 上午10时22分, LeeoNix <leeoni...@gmail.com> wrote:
> 补充一下，你所说的
>
> >"这个地方应该用State模式，而我们则使用了大量的 if, else, switch。这个函数纯粹就是一个万能函数，并且与
> >另一个函数严重耦合，更糟的是函数名也挂羊头卖狗肉。这个地方应该用二分查找，这里则应该用动态规划提高效率..."
> > 好吧，也许你理由还是很充分，你认为磨刀不误砍柴工，你认为.... ， 总之你认为就是应该有文档嘛！但是我们得面对现实的对不对，现实是，你所拥有的只
> > 是一堆代码，放在一个Visual Studio的Solution文件里面，你无法使用心爱的Adobe Reader, Microsoft
> > PowerPoint and Visio，你只能使用对着Visual Studio，阅读一行行代码，所以，你所能考虑的只应该是如何多快好省的搞
> > 懂这些代码。
>
> > 当然，我不是说你应该不写文档。
>
> > 误区二：
>
> > 好吧，无论有没有文档，有一件事情是肯定的，你现在对代码有了一些了解。是时候发表点自己的评价了，于是你说：
>
> > "我们的代码烂到家了！"
>
> > 你的评价是有道理的，因为你的评价基于你对软件开发的真知灼见。你举出了无可动摇的事实，你说：
>
> > "这个地方应该用State模式，而我们则使用了大量的 if, else, switch。这个函数纯粹就是一个万能函数，并且与
> > 另一个函数严重耦合，更糟的是函数名也挂羊头卖狗肉。这个地方应该用二分查找，这里则应该用动态规划提高效率..."总之：
>
> > "这代码真应该从一开始就让我写！"
>
> > 好主意！如果一开始就让你写，或许你会理解所有代码的来龙去脉，你会认为代码本来就应该是这个样子。你会认识到我们为得到这些混乱的
> > 代码，所付出的巨大努力：一个个优秀的程序员，一个个目光犀利的QA，以及大量花数年时间使用我们软件的客户，如辛勤哺育孩子一般，让我们的软件逐渐成
> > 长起来，而有人却认为他很烂？！
>
> > 现在让我们看看我们的代码，看看这个5000行以上的函数，里面署有50位程序员的大名。而他的功能仅仅是显示一个窗口，随着岁月的
> > 积累，他开始变得庞大。但是不像中年发福的人，这个函数的增长，是在积累有用的东西，那就是：Bug fix。有人发现在没有安装Internet
> > Explorer时窗口不能正确的现实，有人为内存不足时正确的现实窗口做了点特殊处理，为了使某个将数据存储与局域网服务器的客户能看到给窗口，我们
> > 还得加点代码；至于丑陋的LoadLibrary的调用，则是为了支持Windows 98以及Linux用户。
>
> > 所有这些bug的发现都是在我们的软件被大量使用 - 测试之后发现的，定位这些bug花了我们大量的精力，时间。在一个个
> > Bugfix 中，我们的软件从一个婴儿 - 单纯，简洁，变得越来越成熟，稳定，越来越善于处理来自客户的需求。然而，随着一个个Bug被修掉，我们
DaiZW
btw：我现在接手的一些2002年的C++代码，里面就有很大量的这样注释。有的甚至 这样写：
//-----begin modify-----
代码。
//-----end modify-----
//modified by leeonix
同, 我对这种注释深恶痛绝.
可悲的是直到现在, 还是经常看到有人这样写............
LeeoNix
1、我比较喜欢一份代码看上去像一个人写的那种，不过有些人喜欢踩个脚印在上面。
2、影响阅读。写代码其实是给别人看的，既然像培养孩子那样写，最好写的漂亮
点，给别人赏心悦目的感觉，别人两三下看代码就知道功能的，而不是看注释。
3、有时候注释不能说明一切。有时候功能修改，不一定注释同步修改。有人写了
bug fix注释。但是另一个人修改了这个功能，但是并没有意识到旁边还有段说
明，但是这段说明早已经不能成为这个功能的说明了，你可以搜索一下类似这个主
题，不少人吃过苦头的。
唉…… 其实没有什么好说的。其实以前那位老兄给我说的解释我早就忘了，我只是
记得他说这个习惯不好。
还是习惯用BUG跟踪系统添加合理的文字比较好。现在这类系统的查询方便多了，
花一点点时间就会把历史都列举出来。
推荐读物《编程匠艺》，功能修改而注释有时候会混淆的问题，在这本书里面有很好
的叙述。
最后再次感激这位老兄，当时他就给我指出很多习惯，包括言语、做人、还有刚才
说的代码风格习惯。他当时和我谈了很久有关不良习惯的问题。
__________________________________________________________________
LeeoNix
DQP 写道:
LeeoNix
举例：
还是那位亦师亦友的老兄。我们用的是Delphi
有一次我和他讨论一个地方到底用record还是用class。
他坚持用class，用class的构造函数来防止内存问题。
但是我坚持用record，然后用内存池来统一解决内存问题。
我记得我花了近两个小时终于说服了他，才同意的。
还好我带着尊敬的心态耐心和他说。
从那时候我就感觉，降低姿态，放低心态来说，这才是最有意义的。
高人一头的心态是在要不得。
__________________________________________________________________
LeeoNix
Tactoth 写道:
LeeoNix
习惯了这种形式或者方法，就不想在修改这种习惯了。
这类顽固想法的人，很难适合团队协作，有些人可能赶鸭子上架的做程序员的，其
实他可能不适合这个职业。
不过这样写的人，至少还能为他人着想。
不管代码里还是BUG跟踪系统里什么都不写得人，那就不说了。唉……
__________________________________________________________________
LeeoNix
DaiZW 写道:
>
> 2009/2/12 LeeoNix <leeo...@gmail.com <mailto:leeo...@gmail.com>>
>
> btw：我现在接手的一些2002年的C++代码，里面就有很大量的这样注释。有
kuku
欣赏这句话，呵呵！
Ke Li
Ke Li
翁翊成
如果他可以很好的运行，并且以后不需要维护了，5000行的函数就这样扔着吧。
但如果是一个长期维护的项目，从我的角度看，重构他吧，否则你的噩梦很可能就来源于他。
Iceberg
1.理想情况下，发现过的bug最好是为它创建一个测试案例以便将来可以反复做自动回归测试，但可惜有些东西不便于进行自动测试，或者是测试起来很繁
琐。
2.理想情况下，文字说明可以写在注释里、或者版本控制系统的log里、或者bugfix跟踪系统的说明里、或者某份设计文档里……，并且期望接手的程
序员会很认真负责地把以上所有内容都先通读一遍，但这都无法完全等同于在代码中、在最接近这个bug的地方、甚至在代码的同一行的行末，写上一句最直接
的说明。接手的程序员也许会偷懒不看以上提到的所有东西，而只是用一个文本编辑器直接改代码，但他这时总会看到我的行末注释吧。
3. No objection.
On 2月12日, 上午11时00分, Stanley Xu <wenhao...@gmail.com> wrote:
> 我来说说我的理解
> 1. 一个bug发现，那么应该有一个对应的新的testcase，别人不需要考虑你是怎么解决的，也不用知道多隐蔽，test case跑不过说明一切
> 2. 如果是真正意义上的fix，那么功能没有改变，所谓的fix的信息可以放在SCM里，放在代码注释里属于扰乱视听
> 3. 如果是个work around，倒是合适在代码里加个新的TODO
>
> Best wishes,
> Stanley Xu
>
> 2009/2/12 Iceberg <iceb...@21cn.com>
LeeoNix
>序员会很认真负责地把以上所有内容都先通读一遍，但这都无法完全等同于在代码中、在最接近这个bug的地方、甚至在代码的同一行的行末，写上一句最直接
>的说明。接手的程序员也许会偷懒不看以上提到的所有东西，而只是用一个文本编辑器直接改代码，但他这时总会看到我的行末注释吧。
你说的，我还是那句话：最怕的就是有人改了但是没有更新注释。
__________________________________________________________________
LeeoNix
Iceberg 写道:
kuku
sjinny
Stanley Xu
1. 看你写的是什么了，大部分都可以通过回归测试来解决，而且自动测试是个一劳永逸的办法。你不妨举几个例子来看看哪些不能通过测试来覆盖。而且有些可以添加到每日的手工测试中。
2. 我不明白的就是为什么下个开发人员需要知道你的一个实现的细节？非要是一种很特别的hacking的方法解决的话，是不是某种程度说明设计和思路有问题？我同意，在非常非常少数的情况下，也许需要一些对特定代码的说明，但是如果经常有，肯定是设计有问题了。而且通常说明应该针对整段代码而不是某一个特定bug的细节
Best wishes,
Stanley Xu
sjinny
勾股定理很简单，但是自己想出来的过程和看书看来的过程一样吗？结果一样吗？
初中时的数学课，那时上课都是先提出问题，然后让学生来解答，之后这个问题的解答就是这次要学的定理。当然，也许有的人是课前预习了的，但是那时我是从来不预习，因为我知道那样就失去了锻炼的机会。
而到了大学的数学课，基本都是先引出一些概念和定理，然后来解释它们，最后找几个题目来说明如何使用。
我觉得后一种方法对学编程来说是很不好的。
其实我以前曾有过一次体会，那时花了一天用VB写了个用鼠标手势进行控制的音乐播放器（当然是用的现成的播放控件），但是由于是想到哪写到哪，所以没有设计、没有文档，一周后我再看时竟然发现自己看不懂了（是真的看不懂了，完全的陌生），好像是别人写的代码一样。那一次让我真正感受到了设计和文档的重要性。
“纸上得来终觉浅，绝知此事要躬行。”
网易邮箱，中国第一大电子邮件服务商
LeeoNix
所以我当时推荐看《实践论》的时候，唉，没有几个人赞成。里面就说了很多理论和
实践如何结合的问题。不需要自己感慨就知道的理念。
自己想出来的和看著作的当然不同，自己想出来的很多时候都是偏颇的。
而书的作者很多时候都是很全面的。只有你亲身系统写过文章的时候才知道，好的
书籍其实真的是作者的心血。
__________________________________________________________________
LeeoNix
sjinny 写道:
> 自己想出来和看书看来是不同的。
> 勾股定理很简单，但是自己想出来的过程和看书看来的过程一样吗？结果一样吗？
> 初中时的数学课，那时上课都是先提出问题，然后让学生来解答，之后这个问题
> 的解答就是这次要学的定理。当然，也许有的人是课前预习了的，但是那时我是
> 从来不预习，因为我知道那样就失去了锻炼的机会。
> 而到了大学的数学课，基本都是先引出一些概念和定理，然后来解释它们，最后
> 找几个题目来说明如何使用。
> 我觉得后一种方法对学编程来说是很不好的。
> 其实我以前曾有过一次体会，那时花了一天用VB写了个用鼠标手势进行控制的音
> 乐播放器（当然是用的现成的播放控件），但是由于是想到哪写到哪，所以没有
> 设计、没有文档，一周后我再看时竟然发现自己看不懂了（是真的看不懂了，完
> 全的陌生），好像是别人写的代码一样。那一次让我真正感受到了设计和文档的
> 重要性。
> “纸上得来终觉浅，绝知此事要躬行。”
>
>
> 在2009-02-12，"Ke Li" <leeo...@gmail.com> 写道：
>
> 另外，LZ，再次推荐你阅读《编程匠艺》(Code Craft)，你所说的问题其实在
> 本书籍里有很系统的阐述。
> 说千言不如静心读点书。
> 2009/2/12 Tactoth <tac...@gmail.com <mailto:tac...@gmail.com>>
>
> 很诚恳的回应leeonix兄，本人非但不是批评的应对着，恰恰相反，本
> 人是一个加入某个产品开发不久的人。
> 所以这篇文章毫无感情色彩，只是我对软件开发的一点小小看法。至于
> 这种稍微夸张的写法，实在是我写作的习惯 :)。
>
> On 2月12日, 上午10时22分, LeeoNix <leeoni...@gmail.com
> 的，后来有同事建议贴到这里来，说是比较适合讨论，希望能抛砖引玉。
> >
> > > 首先我必须有力的反击在软件开发中充满迷惑性的两点误区，据我
> 所知者两点误区已经深深毒害了软件开发人员多年，大大的降低了代码
> 质量。他们是：
> >
> > > 1. 我们的代码应该有很多文档。
> >
> > > 2. 我们的代码似乎很烂。
> >
> > > 首先来看看误区1：
> >
> > > 在软件开发中，新加入一个项目的程序员常常会有这样的抱怨： "
> 我们的代码没有文档"。这种抱怨甚至会得到项目中已经颇有经验的程
> 序员的附和。但其实这
> > > 种抱怨是带有不合理要求的，不应该支持的，是可以驳回的。
> >
> > > 首先，这世界上90+的软件是没有(或缺乏)文档的，千万不要以为
> 在大公司会有很"理想"的写一大堆文档然后才开始写代码的"正规流程
> "。如果不相信，
> > > 可以问问你在大公司，比如Microsoft, IBM等工作的朋友，看看我
> 们耳熟能详的那些软件到底有多少文档。似乎只有外包公司比较重视文
> 档，然而
> > > 敏捷开发的风行也使开发者对书写笨重的文档难以保持耐心。文档
> 与代码的不同步也使许多文档变得失去意义。
> >
> > > 其次，让我们来看看文档对于开发者的意义。也许新加入的项目组
> 成员会想，在理想的情况下，只要让我先看看文档，一点代码都不用
> 看。等我通读完文档后，我
> > > 打开代码就懂得全部的代码啦！然而这真的很幼稚。
> >
> > > 好吧，也许你理由还是很充分，你认为磨刀不误砍柴工，你认
> 为.... ，总之你认为就是应该有文档嘛！但是我们得面对现实的对不
> 对，现实是，你所拥有的只
> > > 是一堆代码，放在一个Visual Studio的Solution文件里面，你无
> 法使用心爱的Adobe Reader, Microsoft
> > > PowerPoint and Visio，你只能使用对着Visual Studio，阅读一
> 行行代码，所以，你所能考虑的只应该是如何多快好省的搞
> > > 懂这些代码。
> >
> > > 当然，我不是说你应该不写文档。
> >
> > > 误区二：
> >
> > > 好吧，无论有没有文档，有一件事情是肯定的，你现在对代码有了
> 一些了解。是时候发表点自己的评价了，于是你说：
> >
> > > "我们的代码烂到家了！"
> >
> > > 你的评价是有道理的，因为你的评价基于你对软件开发的真知灼
> 见。你举出了无可动摇的事实，你说：
> >
> > > "这个地方应该用State模式，而我们则使用了大量的
> if, else, switch。这个函数纯粹就是一个万能函数，并且与
> > > 另一个函数严重耦合，更糟的是函数名也挂羊头卖狗肉。这个地方
> 应该用二分查找，这里则应该用动态规划提高效率..."总之：
> >
> > > "这代码真应该从一开始就让我写！"
> >
> > > 好主意！如果一开始就让你写，或许你会理解所有代码
> 的来龙去脉，你会认为代码本来就应该是这个样子。你会认识到我们为
> 得到这些混乱的
> > > 代码，所付出的巨大努力：一个个优秀的程序员，一个个目光犀利
> 的QA，以及大量花数年时间使用我们软件的客户，如辛勤哺育孩子一
> 般，让我们的软件逐渐成
> > > 长起来，而有人却认为他很烂？！
> >
> > > 现在让我们看看我们的代码，看看这个5000行以上的函
> 数，里面署有50位程序员的大名。而他的功能仅仅是显示一个窗口，随
> 着岁月的
> > > 积累，他开始变得庞大。但是不像中年发福的人，这个函数的增
> 长，是在积累有用的东西，那就是：Bug fix。有人发现在没有安装
> Internet
> > > Explorer时窗口不能正确的现实，有人为内存不足时正确的现实窗
> 口做了点特殊处理，为了使某个将数据存储与局域网服务器的客户能看
> 到给窗口，我们
> > > 还得加点代码；至于丑陋的LoadLibrary的调用，则是为了支持
> Windows 98以及Linux用户。
> >
> > > 所有这些bug的发现都是在我们的软件被大量使用 - 测
> 试之后发现的，定位这些bug花了我们大量的精力，时间。在一个个
> > > Bugfix 中，我们的软件从一个婴儿 - 单纯，简洁，变得越来越成
> 熟，稳定，越来越善于处理来自客户的需求。然而，随着一个个Bug被
> 修掉，我们
> > > 的代码会逐渐零乱，代码中或许会混杂着各种各样的风格，或许会
> 有重复的API调用，或许有些地方必须要提高性能了，甚至或许会有自
> 相矛盾的地方。但是你
> > > 应该感觉得到与这微不足道的缺陷相比，他所能提供的强大的功
> 能，他所具有的巨大的容错性，才是我们代码真正的本色！
> >
> > > 至于那些毛病，我们有你，优秀的开发人员。对于软件
> 进化已成为软件开发主流的当代，代码重构是一个程序员最需要提高的
> 能力。
> >
> > > 况且，从态度来说，一个喜欢自己工作与之上的code
> base的程序员，会有更积极的态度，因而也更能改进现有的代码。
> >
> > > 敬请期待续篇...
>
>
>
>
> ------------------------------------------------------------------------
> 网易邮箱，中国第一大电子邮件服务商 <http://www.yeah.net>