那些令人讨厌的画蛇添足的注释

来源：互联网发布：qpst识别不了端口编辑：程序博客网时间：2024/04/30 13:56

我相信，很多人已经恨死了“该死的代码就是注释”，因为那些没有注释的代码大大降低了代码的可读性，当我们对一个方法进行重用时，我们需要浪费好多时间来验证这代码是否是我们所需要的。于是，我们将那些不写注释的代码的程序猿骂的狗血淋头。

可是，有一天我们发现我们不再像以前那样讨厌那些不写注释的代码了，因为我们发现这些代码所造成的影响比起那些画蛇添足的注释造成的影响要小的多，接下来我们就一起看看那些画蛇添足的注释。

示例代码：

/**

* @function 加载tree

* @author xxxx

* @date 2012-03-26

* treeType应当有以下类型

* 1.all 公司+公司领导+部门+部门领导

* 2.corpL 公司级部门+领导

* 3.corpNL 公司级部门(无领导)

* 4.deptL 部门级科室+部门领导

* 5.deptNL 部门级科室(无部门领导)

* 6.siteT 站点

* 7.plantT 场站

* 8.corpL-B站点下公司+部门，非当前公司只显示到公司

loadTreeAdvance:function (params) {

console.dir(["params", params]);

var siteName = "";

var plantName = "";

var showLevels = 2;

var type = "3";

var withLeaderType = "";

var withPeopleType = "";

var treeType = "", orgDN = "", orgLabel = "";

if (params) {

siteName = params.site.siteName;

plantName = params.plant.plantName;

showLevels = params.showLevels;//显示层数

treeType = params.treeType;//组织机构树类型

type = params.defaultType;//TODO 待移除

this.type = params.defaultType;

withLeaderType = params.withLeaderType;//带领导?

withPeopleType = params.withPeopleType;//带个人?

this.withoutSelfPlant = params.withoutSelfPlant;//带自家电场?

orgDN = params.orgDN;//root DN

orgLabel = params.orgLabel;//root Label

}

var createFolderTree = function (result) {

console.dir([ "loadTree:result", result ]);

var _items = result.get("itemJSON");

var _temp = [];

var _item = null;

if (treeType == "sites") {

_item = this._getItemsObject(_items);

for (var i = 0; i < _item.length; i++) {

_temp.push({

"treeId":_item[i].id,

"DN":_item[i].id,

"name":_item[i].label,

"displayName" : _item[i].label,

"subOrgsBrief":[]

});

}

if(params.isStandardRuleDist){

//XX下发申请中，发往单位树中不包括总部节点

//by xxxx 2012-12-1 17:29:20

//by yyy 增加isSite 项 2012-12-25 16:06:27

var _tempArr = dojo.clone(_temp);

_temp = [];

for ( var k = 0; k < _tempArr.length; k++) {

if(_tempArr[k].name != "总部"){

_temp.push({

"treeId":_tempArr[k].treeId,

"DN":_tempArr[k].DN,

"isSite":true,

"displayName" : _tempArr[k].displayName,

"subOrgsBrief":[]

});

}

}else {

for (var j = 0; j < _items.length; j++) {

_items[j].treeId = _items[j].DN;

_items[j].orgPath= _items[j].name,

_items[j].displayName=_items[j].name,

_temp.push(_items[j]);

}

var data = {

identifier:"treeId",

label:"name",

items:_temp

};

console.dir([ "loadTree:data", data ]);

this.departmentInfo = data;

this.workStore = new dojo.data.ItemFileWriteStore({

"data":data

});

this.workModel = new dijit.tree.ForestStoreModel({

store:this.workStore,

query:{},

rootId:this._rootDN,

rootLabel:this._rootLabel,

childrenAttrs:[ "subOrgsBrief" ]

});

console.dir([ "loadTree : workModel", this.workModel ]);

this.workTree = new dijit.Tree({

model:this.workModel,

openOnClick:false,

persist:false // persist==true is too hard to test

});

this.workTree.placeAt(this.containerNode);

console.dir(["workTree", this.workTree]);

};

var postPayload = {

"desiredPageIndex":"",

"pageSize":1000,

"criterias":{

"type":type,

"siteName":siteName,

"plantName":plantName,

"prefixName":"",

"orgDN":this._rootDN

}

};

this.get("model").retrieveDepartment(postPayload, dojo.hitch(this, createFolderTree));

一、方法的注释，没有明确说明各参数的取值及意义

/**

* treeType应当有以下类型

* 1.all 公司+公司领导+部门+部门领导

* 2.corpL 公司级部门+领导

* 3.corpNL 公司级部门(无领导)

* 4.deptL 部门级科室+部门领导

* 5.deptNL 部门级科室(无部门领导)

* 6.siteT 站点

* 7.plantT 场站

* 8.corpL-B站点下公司+部门，非当前公司只显示到公司

loadTreeAdvance:function (params) {

解析：在这段为方法（加载tree）所作的注释中，没有明确说明params的取值对方法的影响，而仅仅注释了params的一个参数treeType的取值，可能影响的结果。params的其它参数取值对结果是否有影响呢，如果有，会造成什么样的结果呢？

treeType的注释不仅没有增强读者对于此方法的理解，反而让读者更加迷糊。小编试着更换treeType的取值查看返回的结果集。结果，只有发现在8个取值中，只有2个是可行的，其它的取值都不能正常运行。

二、带有疑问，幽默诙谐的注释

withLeaderType = params.withLeaderType; //带领导?

withPeopleType = params.withPeopleType; //带个人?

解析：我承认，看到这样的注释时，我笑了。带领导？还是不带领导？看到这样的疑问注释，我感觉withLeaderType的取值应该是Boolean值，但是我看到var withLeaderType = ""时，我迷惑了。

带有疑问，幽默诙谐的注释的确能够给枯燥无聊的开发工作带来一些乐趣，但是如果别人看了这样的注释也不明白作者是什么意思时，这岂不成了冷笑话。写注释是为了方便他人工作，而不是给别人讲冷笑话。我建议程序猿在工程中的使用的注释尽量简单、直白。

三、带有 TODO 技术债务的注释

type = params.defaultType;//TODO 待移除

解析：刚入行的程序猿，总是被大牛们谆谆教诲，对于不完善的代码，应该用TODO进行标记，这样便于查找自己未完成的任务。然而，更多的时候TODO只是一件装饰，大多数的程序猿并没有闲暇时间来修复留下的TODO。

因此，如果你有充足的时间，请立即重构这段代码，没有时间，也不要留下TODO债务。

四、修复Bug时，注释XX在X年X月X日修复了X功能

//标准制度下发申请中，发往单位树中不包括总部节点

//by xxxx 2012-12-1 17:29:20

//by yyyy 增加isSite 项 2012-12-25 16:06:27

解析：如果xxxx修改的代码有问题，我们可以通过SVN的版本历史记录，找到问题代码。如果xxxx还在项目，我们可以直接联系他。如果他离开了项目，即使写上xxxx的家庭住址，对于解决问题也无任何帮助。

对于这样没有任何帮助的注释，一定不要写。如果需要为修改的代码写注释，请将注释写在提交代码的Comment中。

五、为不能进行测试的代码写注释

persist:false // persist==true is too hard to test

解析：我们必须承认，变量在某些取值下，可能会让测试变的复杂，但这不是变量必须要取某个值的原因。变量的取值是为了保证逻辑的正确性，而不是为了测试方便。