在命名规范的情况 你还会写注释么？

Question

比如一些方法

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

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

// ip转数字
ipToNum() {}

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

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

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

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

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

Answer 1

• 你不应该在每次调用方法的时候写注释，而是应该在声明函数的地方写注释

• 建议每个函数都写相应的注释

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

Answer 2

注释不仅仅是给开发人员看，IDE也要看的，建议按规范来

/**
 * 方法描述
 *
 * @param string $type
 * @return string
*/

Answer 3

注释的主要目的是若干年后你看到代码还能一目了然，所以如果方法名可以看出来干嘛，我一般不写注释

你看看object-c或者swift这两个语言，方法和参数已经将目的表现的很清楚，所以一般不写注释

Answer 4

能通过修改代码解释清楚的问题，不要用注释来解释。
所谓的清楚，是相对于读者而言的。不存在绝对的可读易理解。所以代码命名和注释，中文或英文，缩写或全称，哪个更好理解是取决于读者的。
不懂代码的人看到// /* 就犯怵。不懂业务的人就算你注释里写的很清楚在做什么业务了，他可能还是需要读一本书才能了解这些概念。
所以在追求可读性的时候，想想究竟是对谁可读的。他们会怎么来读这段代码。以此为准来做决定。
注释应该帮助理解而不是阻碍理解，模糊不清的注释，错误的注释（往往是过时的注释），这些都不如没有测试。
注释和代码之间的冗余，和冗余代码一样，会带来维护的成本。如果注释没有带来更多的信息，它是否值回维护它的额外代价？注意这个代价不是现在多敲几个字，而是在代码的整个生命周期里，每次改动，每次review时确保它们一致性的成本。否则，它就会成为上面所说的误导性的注释。

Answer 5

写代码不写注释的人找不到女朋友 :)

Answer 6

我作为一个不了解你这个项目代码的人，如果不看你的注释不明白每个方法的含义。这么说你懂了吗？

Answer 7

多人协同开发的话建议写，个人在开发时也是习惯写注释

Answer 8

写注释,打包的时候去掉不就完了

Answer 9

按照规范来写注释，这样之后可以直接生成文档，而且IDE也能解析到从而提示代码的时候可以显示参数的注释

Answer 10

会。代码自身只能说明它在做什么，而无法说明为什么这样做。

PS: 强烈建议英文不好的人使用中文命名，以免误导苍生！

Answer 11

我们公司的项目前端开发没有很多，基本上就是按照先注释后理解，就是必要性的地方约定哪里需要注释，比如有些方法名一目了然，方法也短，就无所谓写不写，但是有些变量特别长，就可能需要简写一部分，这个时候为了后期的维护，就要求写上注释，我们的spa开发，看文件命名，或者在哪个文件夹下，说明了这个页面的功能，比如在common文件夹里面的header.vue说明这个是公共组件（头部导航栏或者头部信息）,里面的方法一般都是简单命名，这个时候，我个人觉得没多大必要命名，累赘，但是如果一个页面的里面的东西，比如变量或者方法名已经很多了，那么再简单也需要注释，好的代码结构，清晰的注释，能让人开发愉悦，而不是一看别人的代码，就是一句，卧槽，这什么鬼，我就想问问这个变量名是谁取的。。。。，XX,我一看到别人变量是aa,toubu,youxidefen,。。。就头疼，没有注释，乱来的变量，简直是丧心病狂

Answer 12

首先写代码不写注释一定会被人打；
声明函数时要写注释，调用方法一般情况下不用写注释；
团队里不是所有人的英语水平都好，我们这边多人协作的代码还是建议用中文注释；
英语好的请一定用英文注释，这也是为了自己好。

Answer 13

写吧，因为项目久了很多东西都会忘记，即便是自己写的代码，就算命名规范再好，也不如注释看得舒服，特别有时候要把项目交接给别人的时候...，像我们都是按模块去写注释的，这样寻找起来也快，具体的细节一般都不写。

Answer 14

注释还是要写的,项目开发多为团队开发,不仅方法命名需要规范,注释也是必不可少的.不仅要注明方法功能,需要传的参数,是否有返回值,返回值类型都需要写.你就想象队友全是小学生,不懂英语.都给他写明白了.

Answer 15

我都会写 并且函数具体功能 简单描述一下 可能以后迭代的时候 你已经看不懂你自己的代码了 方法名可能只是你现在能看懂 过段时间就看不懂了 并且可能别人也要看你的代码 一定要有注释 你有没有看多注释比代码都多的代码