领导力大挑战
在实施Scrum项目的过程中，Scrum Master的角色是相当关键的，因为他是团队的推动者。本文围绕什么是仆人式领导、仆人式领导的起源、如何将领导力传达给团队、Scrum Master作为仆人式领导者的角色展开叙述，同时重点阐述仆人式领导者应有的基本内外特征。
新闻
该内容已经被标记书签！
标记书签错误，请重试！
注释还是不注释，这是个问题
作者 Abel Avram 译者 张龙 发布于 2010年3月11日
每个开发者都曾在代码中写过注释，有些人的注释很多，为的就是更好地说明代码的意图。本文搜集了关于编写代码注释的一些实践以飨各位读者。
最近，Seattle Area Alt.Net小组的成员们就编写代码注释的必要性和实践进行了激烈的讨论。Kelly Leahy坚持少写注释并编写能够自我说明的代码，因为他相信注释“只会向系统中引入不和谐的声音；一旦修改代码，那些注释就入土为安了”：
编写注释对于大多数人来说是个人的事情，但我本人非常反对写注释，因为一旦修改代码，那些注释就入土为安了——这种情况我见得太多了：注释还在那儿，但代码早就被删除了或是描述的行为被删掉了、代码并没有紧跟注释之后（因为有人在注释和原来的代码之间插入了新的代码）、注释和代码不一致，因为代码被修改了而注释却没有变化。
我觉得这种注释比不写注释还恶心，我憎恨注释。
Leahy并没有完全否定注释的作用，但他只对10,000行代码写了一行注释：
有时注释还是很有用的，比如设计上有不可避免的约束（性能变化等）时就可以加上一些注释。我尽量不写注释，我们大概每10,000+行代码会写一行注释（除了无聊的xmldoc注释，我个人觉得这种注释只对于public API有用，别的地方一无是处）。
Justin Rudd说他得在目前所从事的项目中写大量注释，因为里面的API实在是“太糟糕了”：
目前我正为Visual Studio编写一个源代码控制包。API实在是太糟糕，没办法只能多写注释了，这样我就能想起来为什么在一个地方需要传递Guid.Empty而在另一个地方（看起来很相似的地方）需要传递一个特殊的GUID，否则一切就都乱套了。
我对实现的4个解决方案事件接口加了注释，这样后面的人即便是看到7个方法中有6个似乎没用也不会把他们删掉了。
我对方法为何要返回一个特定的HRESULT加了注释，因为如果返回S_OK的话Visual Studio会崩溃（Connect中是这么说的）。
虽然文档说可以传递null，但你不能这么做，我在这个地方加了注释。
在这个项目中，代码与注释的比例为2：1。
Chris Tavares使用注释来标明bug被修复了：
注释”// doing this because it fixes bug #####“并不是一种坏味道——事实上这是必要的。
然而Brandon Molina认为在代码中通过注释来标明修复的bug并不好，使用版本控制系统才是上策：
如果修复了10个bug该怎么办呢？代码将充斥着大量无用的信息。在这种情况下应该使用版本控制。注释加上diff才是明智之举。
Brad Wilson补充了一条原则以避免差劲的注释：
“Why”注释 == good
“How”注释== suspect
Timo Hilden写了一篇关于代码注释的文章，他坚持认为好的注释是非常有必要的：
不理会代码注释很容易，但还是让我们面对它吧。作为程序员，我们不指望获得普利策奖（普利策奖是由美国颁发的一个奖项，主要用于奖励那些在新闻报道、文学创作以及音乐创作方面有杰出贡献的人，该奖项由美籍匈牙利人约瑟夫 普利策创建，现在由位于纽约的哥伦比亚大学负责——译者注），因此写不写注释与表达能力强不强没有什么关系，这仅仅事关懒惰与否。
坦白地说，更糟糕的是在代码需要注释的时候却没有编写。首先，这间接地说明了程序员缺少对同伴的尊重。每个人都知道查看大量的类是多么不爽的一件事，尤其是其中包含很多含义模糊、自我描述性差的函数，更有甚至，之前编写代码的人度假去了、离职了或是由于其他原因找不到了。程序员应该是个艺术家而同伴则是其观众。作为艺术家，应该尊重我们的观众。
其次，不写注释表明程序员太过于自负了。当然了，在写代码的时候我们很清楚自己在干什么，编程的时候脑子里会有很多想法，但下一次再看自己所编写的代码时将很可能无法找回当初的想法。以上这些都是常事，这需要我们在适当的地方编写具有描述力的注释。
Hilden并不赞同取消文档（几年前由Scott Swigart和Jeff Atwood提出的观点）的做法，看看下面这个过度注释的代码片段：
// Declare category id for products
const int prodCategoryId = 1024;
// Create an iterator over products
vector<Product>::iterator iter = products_.begin();
// Iterate through all products
for ( ; iter != products_.end(); ++iter )
{
// Assign categody id to each product
iter->AssignCategoryId( prodCategoryId );
}
他建议将上面这些注释合并成一行用于说明代码的总体意图而非每行的意思：
// Assign categody id to each product
const int prodCategoryId = 1024;
vector<Product>::iterator iter = products_.begin();
for ( ; iter != products_.end(); ++iter )
{
iter->AssignCategoryId( prodCategoryId );
}
各位读者，你采取何种手段编写注释呢？这些方法是公司的硬性规定还是自己选择的呢？你支持“编写尽可能少的注释”这种观点么？是否相信后继者能理解你所编写的代码么？你认为程序员是否需要花时间对代码中那些不太好理解的地方加注释么？
查看英文原文：To Comment or Not to Comment
译者 张龙 热衷于编程，乐于分享，对新技术有强烈的探索欲，对Java轻量级框架有一定研究。
如何恰当的命名函数和变量？
发表人
闫 菲
发表于
Re: 如何恰当的命名函数和变量？
发表人
nie runshine
发表于
Re: 如何恰当的命名函数和变量？
发表人
李 冬
发表于
Re: 如何恰当的命名函数和变量？
发表人
Cui Guangyu
发表于
Re: 如何恰当的命名函数和变量？
发表人
侯 伯薇
发表于
Re: 如何恰当的命名函数和变量？
发表人
Dong Nan
发表于
Re: 如何恰当的命名函数和变量？
发表人
侯 伯薇
发表于
Re: 如何恰当的命名函数和变量？
发表人
闫 菲
发表于
Re: 如何恰当的命名函数和变量？
发表人
张 亮
发表于
Re: 如何恰当的命名函数和变量？
发表人
朱 敏
发表于
Re: 如何恰当的命名函数和变量？
发表人
谢 邵虎
发表于
说得好
发表人
黄 雯
发表于
Re: 说得好
发表人
朱 敏
发表于
尽量写只需要最小注释的代码
发表人
田 乐
发表于
每一行代码都写注释
发表人
Jun Ran
发表于
-
我认为好的code需要极少的注释就会清晰明了。
然而对于我来讲恰当的命名函数和变量感觉困难，不能准确的选择英文。希望大家给个建议！ -
用汉语拼音阿鲁~囧
-
拼音始终是大问题 拼音相同的词在汉语中太多了 注释 注视 主食 诸事 主事。。。
-
你可以用中文做变量名。。。
-
To：felix yan
不知道你现在使用的是什么语言，什么开发工具，之前我曾经对于“中文编程方式”做了一些验证工作，实践证明，在Java、.NET、VBA、Oracle等等环境中，对变量名、函数名、字段名、表名等等使用中文来命名不失为一种很简单的方法。而且开发环境和工具完全支持这种方式。
前几天我开发一个VBA宏的过程中，还用了这种方法，只不过在开头我会写上几个英文字母，这样更有利于智能感知，呵呵。
就是不知道你的开发团队的开发规范是否允许这样做，：） -
能但不推荐
-
我想知道不推荐的原因是什么，呵呵？
如果是跨国家合作开发，可能会有人不认识中文，那肯定是不能这样做了。
但是单纯从技术角度上来说，其实使用中文没有问题。
做出来的程序，至少在可维护性上会有很大的提高。
至于编译性能、运行性能方面，暂时我还不是很确定，但至少从我做的这些程序看没有问题，呵呵。 -
感谢大家的回复！！
使用中文名或汉语拼音对于我来讲是不可能的，原因有两个：其一，目前我工作在外企，所有的文档、书面的东西全得是英文。其二，我感觉即使看code的都是中国人，用汉语编程也感觉很奇怪。 -
用中文编程，是感觉怪怪的。就好像男生穿短裙一样，不是不能穿，但穿起来很扎眼。
-
“Why”注释 == good
“How”注释== suspect -
哈哈，你要用一个英文单词来命名，当然有难度；很多人不喜欢用下划线，结果他们就找不到答案。
-
Agreed！
-
在VBA中使用中文，给系统切换一个语言环境，你写的东西就嗝屁了。
-
理想的情况是让注释最小化，让代码说话。但是注释是知识/经验传递的有效手段，它在第一时间第一地点给维护者帮助。除了注释意外给代码增加解释的方式还很多，如使用良好的分析方式（记录下代码表述的对话过程），良好的分层的测试。它们都能让代码更好的说话，介绍对注释的依赖。
在胶水代码，和自动化脚本这些面向过程的脚本里面，注释比在其它环境显得更有用，所以我个人喜欢在配置文件、自动化脚本里面多花一些篇幅写注释。 -
我曾经遇到一种极端情况，我们的一个客户要求每一行代码都写注释，当时觉得这很浪费，现在想想看，每一行代码都注释，可以解决Leahy提到的问题：
1）注释还在那儿，但代码早就被删除了或是描述的行为被删掉了、
2）代码并没有紧跟注释之后（因为有人在注释和原来的代码之间插入了新的代码）、
3）注释和代码不一致，因为代码被修改了而注释却没有变化。
因为每一行代码都与其注释绑定了，它们共存亡，所以可以很大程度上避免以上3点诟病。
15 条回复
关注此讨论 回复