黑马程序员技术交流社区

标题: 新人不能不知,如何撰写PHP代码注释 [打印本页]

作者: huawei    时间: 2016-5-13 14:37
标题: 新人不能不知,如何撰写PHP代码注释
本帖最后由 huawei 于 2017-3-5 11:49 编辑

新人不能不知,如何撰写PHP代码注释


代码注释,可以说是比代码本身更重要。告诫新人,一定要养成写注释的习惯,否则只能是损人不利己。
这里有一些方法可以确保你写在代码中的注释是友好的,总结起来就是"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可以为你检查拼写。如果没有这个功能,那就去下载插件,自己动手!



七、要多多练习(√

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



八、要审查别人的注释(√

在代码审查时,我们往往会忽略查看注释。不要怕要求更多的注释,你应该提出质疑。如果每个人都养成写好注释的好习惯,那么世界将会更美好。


九、对注释一定要知道的的精华总结




精华推荐:

2017最新PHP学习路线图(附完整视频资源)+源码+技巧/经验+求职+前景总结!
连续两班仅6日就业率突破53%,看2016PHP课程升级是否成功!
视频集合:众多老学员呐喊:"为什么我选传智PHP"!

作者: Deleteying    时间: 2016-9-21 10:21
都用中文注释行吗?
作者: eddies    时间: 2016-11-1 16:04
都用中文注释行
作者: 小小海    时间: 2016-11-9 20:26
sdyafgsaudhrf
作者: hsyb    时间: 2016-11-16 17:25
cahakakakankank
作者: jason_QS    时间: 2016-11-18 22:27
PHP代码注释
作者: 夜歌行    时间: 2016-11-20 15:48
fffffffffffffffffffffffffffffffffff
作者: piliyouxia121    时间: 2016-11-23 15:42
谢谢谢谢谢谢谢谢谢谢
作者: xxt598316205    时间: 2016-11-24 18:09
DIHDFJHDJBDFJJFB
作者: ch123cn    时间: 2016-11-25 16:53
RE: 新人不能不知,如何撰写PHP代码注释 [修改]
作者: 肖肖肖    时间: 2016-12-12 23:56
谢谢分享!!!
作者: 雨落风停    时间: 2016-12-14 16:22
啊哈哈哈哈哈哈哈啊哈哈
作者: 耀耀耀耀    时间: 2016-12-14 16:31
1212121212121212
作者: Rakishly    时间: 2016-12-14 16:34
如何撰写PHP代码注释
作者: fanphp    时间: 2016-12-23 21:38
谢谢楼主分享
作者: www6688w    时间: 2016-12-27 11:56
打土豪规范不好规范化
作者: lcy1069    时间: 2016-12-29 15:24
!@!!!!!!!!!!!!!!!
作者: VC丶万人敬仰    时间: 2017-1-3 15:27
谢谢谢谢谢谢!!!!!
作者: heychm    时间: 2017-1-12 15:31
666666666666666
作者: 1317181388    时间: 2017-2-2 23:47
感谢楼主分享
作者: 707621521    时间: 2017-2-6 14:48
注释是能帮助自己和别人理解代码
作者: 646547989    时间: 2017-2-10 17:08
写的棒棒的,学到了……
作者: molei886    时间: 2017-2-16 11:06
我而且头发都特润膏
作者: fjdaslfjk    时间: 2017-2-16 11:11
撰写PHP代码注释
作者: 小丑鸭    时间: 2017-2-16 14:43
gg
作者: devil_joker@qq.    时间: 2017-2-23 16:21
6666666666
作者: mht    时间: 2017-3-2 16:00
666666666666666666
作者: 云烟    时间: 2017-3-6 17:41
qwertyuiodfghjkl
作者: jxson    时间: 2017-3-7 21:53
谢谢分享哈哈哈!!!
作者: Overflow    时间: 2017-3-13 12:02
1111111111111111111111111
作者: datong    时间: 2017-3-13 15:37

作者: 瞬间回忆    时间: 2017-3-26 16:43
如何撰写PHP代码注释
作者: 今天吃什么    时间: 2017-4-6 14:38
学习学习。
作者: 小花99    时间: 2017-4-17 19:02
楼主真好
作者: 沈唁    时间: 2017-4-24 08:30
感谢楼主分享
作者: 咿呀咿呀哟    时间: 2017-5-1 14:40
感谢分享。。。
作者: 踏上PHP征程    时间: 2017-5-19 22:34
谢谢分享
作者: worldtongf    时间: 2017-5-20 23:07
新人不能不知,如何撰写PHP代码注释 [修改]
作者: qq280385639    时间: 2017-6-27 14:10

都用中文注释行
*滑动验证:
作者: qq280385639    时间: 2017-6-27 14:11

都用中文注释行 可以了吧

作者: xxiaogongchang    时间: 2017-7-14 19:52
看看 学习下

作者: yuanlinjiayou    时间: 2017-8-28 14:55
回复回复回复回复回复
作者: ap2017    时间: 2017-9-11 16:15
如何撰写PHP代码注释
作者: 摇摆的稻草人    时间: 2018-5-24 17:23
1111111111111111111111
作者: 六点二十二    时间: 2018-9-18 22:05
好内容要学习!!!!!!!!!!!!!!!!!
作者: uuuqqq    时间: 2018-10-7 06:21
这东西找了好久勒,谢谢!!

作者: 蜗牛泛泛    时间: 2018-10-22 18:07
6666666666
作者: ropang    时间: 2018-11-16 17:47
6666666666666666





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