0

比如一些方法

// 封装链路信息数据
formatLinksInfo() {}

// 获取节点坐标数据
getNodesPosition() {}

// ip转数字
ipToNum() {}

// 判断元素是否全部选中
isAllElemsActive() {}

// 右键菜单选项
itemContextMenu() {}

if(target.classed('topo')){} // 拓扑图情况
if(target.classed('node')){} // 节点
if(target.classed('link')){} // 链路

比如像这种命名 不写注释感觉也能通过方法名或者类名 也能看懂,
但自己还是都写了 现在code review看来觉得很冗余

问一下你们关于代码注释编写原则是啥呢,能通过命名读懂的都不写么?

骁飞 20
2017-07-28 提问

查看全部 15 个回答

8

已采纳
  • 你不应该在每次调用方法的时候写注释,而是应该在声明函数的地方写注释
  • 建议每个函数都写相应的注释

    • 你自己写代码存在主观性,你觉得规范,其实不一定规范,或许可以说不一定全面;
    • 每个人理解方法是不一样的,你觉得命名规范了,那也许是真的很规范,但是并不是所有人都能一下子看懂,如果要整个遍历一下方法实现过程这是非常浪费时间的,别人看到一个函数应该立刻能从注释和方法名知道这个函数是干什么的;
    • 函数名写的再好,我也只能大概猜到这个函数是干什么的,但是我对函数的参数和返回值类型等信息一无所知
    • 总而言之,空间换时间,一次时间换以后的N次时间是非常值得的
  • 建议写英文注释,这样review起来更加简洁,不显得那么格格不入,不要觉得什么自己或者其他人英文底子不好,网上各种英汉词典,多写英文注释遇到不知道的还能多学几个英文单词
1

我强烈反对问出这种问题的人写英文注释。因为命名通常是英文的,如果命名说不清楚基本信息,说明这命名不好,也就是这人英文不好……

比如 classed 是个什么鬼?ipToNum 是谁教的?(IP 的数字表示叫那个叫 digit。number 是数,比如 IPv4 的 32 位无符号整型表示)getNodesPosition 是所有的节点都挤一块了?

依云 · 2017年07月28日

2

你说的有道理,不过人都是从不会到会,代码都是从丑陋到优雅的,不能因为写的不好而不去尝试不是么?也许你担心丑陋的注释会让其他同事倒胃口或者误解,那刚入门的小白是不是都不能和工作好几年的在同一个项目了,我觉得这个问题可以通过code review来解决,当然如果没有code review等哪天哪个同事抱怨的时候像他提个建议咱们互相提merge request review吧 ^_^

Tony_Zby · 2017年07月28日

展开评论

推广链接