黑马程序员技术交流社区

标题: 代码注释中的5要与3不要 [打印本页]
作者: 小李探花    时间: 2015-10-7 22:34
标题: 代码注释中的5要与3不要
代码注释，可以说是比代码本身更重要。这里有一些方法可以确保你写在代码中的注释是友好的：
不要重复阅读者已经知道的内容
能明确说明代码是做什么的注释对我们是没有帮助的。
[size=1em]
[size=1em]1

[size=1em]2

[size=1em]3

[size=1em]4

[size=1em][size=1em]// If the color is red, turn it green
[size=1em]if (color.is_red()) {
[size=1em]  color.turn_green();
[size=1em]}



要注释说明推理和历史
如果代码中的业务逻辑以后可能需要更新或更改，那就应该留下注释:)
[size=1em]
[size=1em]1

[size=1em]2

[size=1em]3

[size=1em]4

[size=1em]5

[size=1em]6

[size=1em]7

[size=1em]8

[size=1em]9

[size=1em]10

[size=1em]11

[size=1em]12

[size=1em][size=1em]/* The API currently returns an array of items
[size=1em]even though that will change in an upcoming ticket.
[size=1em]Therefore, be sure to change the loop style here so that
[size=1em]we properly iterate over an object */

[size=1em]var api_result = {items: ["one", "two"]},
[size=1em]    items = api_result.items,
[size=1em]    num_items = items.length;

[size=1em]for(var x = 0; x < num_items; x++) {
[size=1em]  ...
[size=1em]}



同一行的注释不要写得很长
没什么比拖动水平滚动条来阅读注释更令开发人员发指的了。事实上，大多数开发人员都会选择忽略这类注释，因为读起来真的很不方便。
[size=1em]
[size=1em]1

[size=1em]2

[size=1em]3

[size=1em]4

[size=1em][size=1em]function Person(name) {
[size=1em]  this.name = name;
[size=1em]  this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let's do it
[size=1em]}



要把长注释放在逻辑上面，短注释放在后面
注释如果不超过120个字符那可以放在代码旁边。否则，就应该直接把注释放到语句上面。
[size=1em]
[size=1em]1

[size=1em]2

[size=1em]3

[size=1em]4

[size=1em]5

[size=1em]6

[size=1em]7

[size=1em]8

[size=1em]9

[size=1em]10

[size=1em]11

[size=1em][size=1em]if (person.age < 21) {
[size=1em]  person.can_drink = false; // 21 drinking age

[size=1em]  /* Fees are given to those under 25, but only in
[size=1em]     some states. */
[size=1em]  person.has_car_rental_fee = function(state) {
[size=1em]    if (state === "MI") {
[size=1em]      return true;
[size=1em]    }
[size=1em]  };
[size=1em]}



不要为了注释而添加不必要的注释
画蛇添足的注释会造成混乱。也许在学校里老师教你要给所有语句添加注释，这会帮助开发人员更好地理解。但这是错的。谁要这么说，那你就立马上给他个两大耳刮子。代码应该保持干净简洁，这是毋庸置疑的。如果你的代码需要逐行解释说明，那么你最需要做的是重构。
[size=1em]
[size=1em]1

[size=1em]2

[size=1em]3

[size=1em]4

[size=1em]5

[size=1em]6

[size=1em]7

[size=1em][size=1em]if (person.age >= 21) {
[size=1em]  person.can_drink = true; // A person can drink at 21
[size=1em]  person.can_smoke = true; // A person can smoke at 18
[size=1em]  person.can_wed = true; // A person can get married at 18
[size=1em]  person.can_see_all_movies = true; // A person can see all movies at 17
[size=1em]  //I hate babies and children and all things pure because I comment too much
[size=1em]}



注释要拼写正确
不要为代码注释中的拼写错误找借口。IDE可以为你检查拼写。如果没有这个功能，那就去下载插件，自己动手！
要多多练习
熟能生巧。试着写一些有用的注释，可以问问其他开发人员你的注释是否有用。随着时间的推移，你会慢慢懂得怎样才算是友好的注释。
要审查别人的注释
在代码审查时，我们往往会忽略查看注释。不要怕要求更多的注释，你应该提出质疑。如果每个人都养成写好注释的好习惯，那么世界将会更美好。
总结
注释是开发进程中非常重要的一部分，但我们不应该为了注释而注释。注释应该是有用的，简洁的，应该是对代码的一种补充。注释不应该用于逐行地解释代码，相反，它应该用于解释业务逻辑，推理以及对将来的启示。
译文链接：http://www.codeceo.com/article/comments-do-and-dont.html
英文原文：Do’s and Don’ts of Code Comments
翻译作者：码农网 – 小峰

作者: 逗你玩儿LLY    时间: 2015-10-11 12:25
以后会多注意的



欢迎光临 黑马程序员技术交流社区 (http://bbs.itheima.com/) 黑马程序员IT技术论坛 X3.2