登录  /  注册
PHP代码注释小细节
大家讲道理
发布: 2023-03-05 10:04:01
原创
1124人浏览过
代码注释,可以说是比代码本身更重要。告诫新人,一定要养成写注释的习惯,否则只能是损人不利己。这里有一些方法可以确保你写在代码中的注释是友好的,总结起来就是"5要与3不要"
一、不要重复阅读者已经知道的内容(×

一些光看方法名,光看代码就能看出来功能的就没必要写注释,

// If the color is red, turn it green
if (color.is_red()) {
  color.turn_green();
}
登录后复制
二、要注释说明推理和历史(√

如果代码中的业务逻辑以后可能需要更新或更改,那就应该留下注释:
/* The API currently returns an array of items
even though that will change in an upcoming ticket.
Therefore, be sure to change the loop style here so that
we properly iterate over an object */
var api_result = {items: ["one", "two"]},
    items = api_result.items,
    num_items = items.length;
for(var x = 0; x < num_items; x++) {
  ...
}
登录后复制
三、同一行的注释不要写得很长(×

没什么比拖动水平滚动条来阅读注释更令开发人员发指的了。事实上,大多数开发人员都会选择忽略这类注释,因为读起来真的很不方便。
function Person(name) {
  this.name = name;
  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
}
登录后复制
四、要把长注释放在逻辑上面,短注释放在后面(√

注释如果不超过120个字符那可以放在代码旁边。否则,就应该直接把注释放到语句上面。
if (person.age < 21) {
  person.can_drink = false; // 21 drinking age
  /* Fees are given to those under 25, but only in
     some states. */
  person.has_car_rental_fee = function(state) {
    if (state === "MI") {
      return true;
    }
  };
}
登录后复制
五、不要为了注释而添加不必要的注释(×

画蛇添足的注释会造成混乱。也许在学校里老师教你要给所有语句添加注释,这会帮助开发人员更好地理解。但这是错的。谁要这么说,那你就立马上给他个两大耳刮子。代码应该保持干净简洁,这是毋庸置疑的。如果你的代码需要逐行解释说明,那么你最需要做的是重构。
if (person.age >= 21) {
  person.can_drink = true; // A person can drink at 21
  person.can_smoke = true; // A person can smoke at 18
  person.can_wed = true; // A person can get married at 18
  person.can_see_all_movies = true; // A person can see all movies at 17
  //I hate babies and children and all things pure because I comment too much
}
登录后复制
六、注释要拼写正确(√

不要为代码注释中的拼写错误找借口。IDE可以为你检查拼写。如果没有这个功能,那就去下载插件,自己动手!

七、要多多练习(√
熟能生巧。试着写一些有用的注释,可以问问其他开发人员你的注释是否有用。随着时间的推移,你会慢慢懂得怎样才算是友好的注释。

八、要审查别人的注释(√
在代码审查时,我们往往会忽略查看注释。不要怕要求更多的注释,你应该提出质疑。如果每个人都养成写好注释的好习惯,那么世界将会更美好。
九、对注释一定要知道的的精华总结
注释是开发进程中非常重要的一部分,但我们不应该为了注释而注释。注释应该是有用的,简洁的,应该是对代码的一种补充。注释不应该用于逐行地解释代码,相反,它应该用于解释业务逻辑,推理以及对将来的启示。
相关标签:
来源:php中文网
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn
作者最新文章
热门教程
更多>
最新下载
更多>
网站特效
网站源码
网站素材
前端模板
关于我们 免责申明 意见反馈 讲师合作 广告合作 技术文章
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号 技术交流群
PHP中文网订阅号
每天精选资源文章推送
PHP中文网APP
随时随地碎片化学习
PHP中文网抖音号
发现有趣的

Copyright 2014-2023 //m.sbmmt.com/ All Rights Reserved | 苏州跃动光标网络科技有限公司 | 苏ICP备2020058653号-1

 | 本站CDN由 数掘科技 提供

登录PHP中文网,和优秀的人一起学习!
全站2000+教程免费学