代码注释的作用  --- 为自己,也为别人。

永远不要过于相信自己的理解力!当你思路通畅,思如泉涌,进入编程境界,你可以很流畅的实现某个功能,但这种一泻千里的流畅可能只停留在了当时的状态。当你几个月,甚至是几个星期后看到你的代码,你可能会想,“这是哪位风骚少年堆的代码,他在干神马!?”。更不要讲更长的时间了。。

当你站在自己的代码面前尚且如此时,那么如果有和我们合作的小伙伴呢?考虑下他们的感受吧(=_=!)。                                                                                            

。。。所以,小伙伴们,从现在开始,请注释你的代码吧!

整理了一些网上的东西加上自己理解,供参考 (这里只说php)。

php里的代码注释主要有以下三种方法:

1.以“/*"开始并且以"*/"结束的多行注释方法 (当然,只要你愿意,单行也是没问题的)。

2.以 ”//"开始的单行注释。

3.以“#”开始的单行注释。

再介绍下符合PHPDoc风格的注释。好了,还是先说下PHPDoc。。。

PHPDoc的做法是在每个函数、类或变量定义前放置一个注释块。并不是所有情况下都要求如此,只是在必要的情况下才这么做。

   每个注释块最前面是一个描述,然后是一个或多个可选的参数。例如,向一个函数增加PHPDoc注释时,可以指定输入参数和返回值数据。显然,为变量定义所编写的PHPDoc注释则包含不同的信息。

   以下代码显示了为一个简单的用户自定义函数编写PHPDoc注释的例子:

   首先要注意注释块如何开始。/**指示PHPDoc解析器一个PHPDoc注释已经开始。

   注释块的第一行是一个简短的描述。一般在此只写函数、类或变量的名。

   注释块中下一部分是一个比较长的描述。在这里大多以一种黑盒的观点描述函数、类或变量的作用。也就是说,它会做什么,而不是它怎样做。所有具体的功能或繁杂的逻辑都由代码中的标准注释来解释。

   尽管不是必需的,不过通常的约定是在/** … */块每行起始处包含一个星号。这主要是为了提高可读性,还能容易地发现整个PHPDoc块。

   注释块中最后一部分包含各个PHPDoc参数,解析器用这些参数来更好地链接API文档,从而为你提供实用的文档。每个参数最前面是一个@,后面紧跟着参数名,然后是该参数所需的信息。

    这个例子中可以看到@param和@return参数。@param用于指定函数参数的各个方面:首先是参数的类型(在这里,第一个参数是一个字符 串);接下来是参数名(这里是$name);最后是一个简短的描述,说明输入的数据应当包含哪些内容。@return参数用于提供函数所返回数据的有关信 息:先指定数据的类型,然后是返回数据所包含内容的一个简短描述。

下面列下一些PHPDoc参数。

  1. <?php
  2. /**
  3. * @name 名字
  4. * @abstract 申明变量/类/方法
  5. * @access 指明这个变量、类、函数/方法的存取权限
  6. * @author 函数作者的名字和邮箱地址
  7. * @category 组织packages
  8. * @copyright 指明版权信息
  9. * @const 指明常量
  10. * @deprecate 指明不推荐或者是废弃的信息MyEclipse编码设置
  11. * @example 示例
  12. * @exclude 指明当前的注释将不进行分析,不出现在文挡中
  13. * @final 指明这是一个最终的类、方法、属性,禁止派生、修改。
  14. * @global 指明在此函数中引用的全局变量
  15. * @include 指明包含的文件的信息
  16. * @link 定义在线连接
  17. * @module 定义归属的模块信息
  18. * @modulegroup 定义归属的模块组
  19. * @package 定义归属的包的信息
  20. * @param 定义函数或者方法的参数信息
  21. * @return 定义函数或者方法的返回信息
  22. * @see 定义需要参考的函数、变量,并加入相应的超级连接。
  23. * @since 指明该api函数或者方法是从哪个版本开始引入的
  24. * @static 指明变量、类、函数是静态的。
  25. * @throws 指明此函数可能抛出的错误异常,极其发生的情况
  26. * @todo 指明应该改进或没有实现的地方
  27. * @var 定义说明变量/属性。
  28. * @version 定义版本信息
  29. */
  30. function XXX($a){..}

注释规范

a.注释必须是

/**
* 注释内容
*/

的形式

b.对于引用了全局变量的函数,必须使用glboal标记。

c.对于变量,必须用var标记其类型(int,string,bool…)

d.函数必须通过param和return标记指明其参数和返回值

e.对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可

f.调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。

g.必要的地方使用非文档性注释,提高代码易读性。

h.描述性内容尽量简明扼要,尽可能使用短语而非句子。

i.全局变量,静态变量和常量必须用相应标记说明

再示例

  1. <?php
  2. /**
  3. * Sample File 2, phpDocumentor Quickstart
  4. *
  5. * This file demonstrates the rich information that can be included in
  6. * in-code documentation through DocBlocks and tags.
  7. * @author Greg Beaver <cellog@php.net>
  8. * @version 1.0
  9. * @package sample
  10. */
  11.  
  12. //PHP code
  13.  
  14. /**
  15. * A sample function docblock
  16. * @global string document the fact that this function uses $_myvar
  17. * @staticvar integer $staticvar this is actually what is returned
  18. * @param string $param1 name to declare
  19. * @param string $param2 value of the name
  20. * @return integer
  21. */
  22. function firstFunc($param1, $param2 = 'optional') {
  23. static $staticvar = 7;
  24. global $_myvar;
  25. return $staticvar;
  26. }

以上列出的PHPDoc参数(如@param)比较多,并不是每个函数都要写这么多。根据环境和函数的功能不同选取合适的注释标记做注释。下面选取的laravel框架的数据库文件的log函数(方法)注释及log函数。供大家参考。

  1. /**
  2. * Log the query and fire the core query event.
  3. *
  4. * @param string $sql
  5. * @param array $bindings
  6. * @param int $start
  7. * @return void
  8. */
  9. protected function log($sql, $bindings, $start)
  10. {
  11. $time = number_format((microtime(true) - $start) * 1000, 2);
  12.  
  13. Event::fire('laravel.query', array($sql, $bindings, $time));
  14.  
  15. static::$queries[] = compact('sql', 'bindings', 'time');
  16. }

说千道万,希望小伙伴们养成注释代码的习惯,贵在坚持。规范代码,规范注释风格。让自己更有逻辑性,更专业。共勉。

最后, 以上如有错误之处,请大家指正。另有部分内容摘自网络,如有版权问题,请联系我。:-D

关于php注释那些事的更多相关文章

  1. Go 语言实践(一)

    本文由Austin发表 指导原则 我们要谈论在一个编程语言中的最佳实践,那么我们首先应该明确什么是"最佳".如果您们听了我昨天那场讲演的话,您一定看到了来自 Go 团队的 Russ ...

  2. java web开发中的奇葩事web.xml中context-param中的注释

    同事提交了代码.结果除同事之外,其他人全部编译报错.报错说web.xml中配置的一个bean 没有定义.按照报错提示,各种找,无果. 由于代码全部都是提交到svn主干,之前也没有做过备份,只能一步一步 ...

  3. OpenNLP:驾驭文本,分词那些事

    OpenNLP:驾驭文本,分词那些事 作者 白宁超 2016年3月27日19:55:03 摘要:字符串.字符数组以及其他文本表示的处理库构成大部分文本处理程序的基础.大部分语言都包括基本的处理库,这也 ...

  4. Ctrl-A全选这点事(C#,WinForm)

    所有的文本框,不管单行多行都Ctrl-A全选就好了吧?是啊,很方便.Windows的软件基本都是这样.可为什么我们自己制作的WinForm就默认不是这样呢?谁知道呢,可能是WinForm饱受诟病,要改 ...

  5. XML通过XSL格式化的那点事(XML到自定义节点折叠显示)

    引言 有时我们想看下系统生成的XML文件(如XML格式的Project文件),如果文件结构简单,我们浏览器看起来还比较方便,但是随着XML schema复杂后就变得让人头疼啦,单独写一个程序去做展现又 ...

  6. Java编程中“为了性能”需做的26件事

    1.尽量在合适的场合使用单例 使用单例可以减轻加载的负担,缩短加载的时间,提高加载的效率,但并不是所有地方都适用于单例,简单来说,单例主要适用于以下三个方面: (1)控制资源的使用,通过线程同步来控制 ...

  7. 关于几种编程过程中的注释(TODO、FIXME、XXX等)

    最近看别人写的代码,注意到很多规范的代码的注释写的都特别好.只是不太明白TODO.FIXME这些事什么意思.查阅资料,看到一篇博客,遂转载而来,以供今后查阅. (转载地址http://www.cnbl ...

  8. JAVA编程“性能说”(java编程需要做的26件事)

    转载于 http://www.csdn.net/article/2012-06-01/2806249 最近的机器内存又爆满了,除了新增机器内存外,还应该好好review一下我们的代码,有很多代码编写过 ...

  9. Java你可能不知道的事(3)HashMap

    概述 HashMap对于做Java的小伙伴来说太熟悉了.估计你们每天都在使用它.它为什么叫做HashMap?它的内部是怎么实现的呢?为什么我们使用的时候很多情况都是用String作为它的key呢?带着 ...

随机推荐

  1. 又写了两个实用的微信小程序

    忙里偷闲,最近又写了两个小程序. 一个是手机壁纸小程序,名字叫[来搜图],特点是界面干净清爽,没有多余的东西.开发这个是因为讨厌市面上那些壁纸app那样那么多的广告,真的太影响体验了.而且小程序更加轻 ...

  2. tensorflow中添加L2正则化损失

    方法有几种,总结一下方便后面使用. 1. tensorflow自动维护一个tf.GraphKeys.WEIGHTS集合,手动在集合里面添加(tf.add_to_collection())想要进行正则化 ...

  3. win10下VSCode+CMake+Clang+GCC环境搭建

    win10下VSCode+CMake+Clang+GCC环境搭建 win10下VSCode+CMake+Clang+GCC环境搭建 安装软件 VSCode插件安装 新建文件夹, 开始撸代码 main. ...

  4. asp.net开源流程引擎API开发调用接口大全-工作流引擎设计

    关键词: 工作流引擎 BPM系统 接口调用 工作流快速开发平台  工作流流设计  业务流程管理   asp.net 开源工作流 一.程序调用开发接口二.   接口说明 所谓的驰骋工作流引擎的接口,在B ...

  5. Java读源码之ThreadLocal

    前言 JDK版本: 1.8 之前在看Thread源码时候看到这么一个属性 ThreadLocal.ThreadLocalMap threadLocals = null; ThreadLocal实现的是 ...

  6. idea2019版与maven3.6.2版本不兼容引发的血案

    昨天遇到了点问题解决浪费了一些时间(导致更新内容较少)回顾下问题 项目出现Unable to import maven project: See logs for details 翻了好多博客 莫名的 ...

  7. Json模块(dumps、loads、dump、load)函数篇

    # dumps.loads函数 """json.dumps()用于将dict类型的数据转成strjson.loads()用于将str类型的数据转成dict. " ...

  8. win10下git与gitlab安装与文件上传

    目前了解到的版本管理工具有三种:gitlab  GitHub 和 码云 个人感觉 gitlab 在公司用的较多 便于协同办公   GitHub各种资源有很多,适合个人使用   码云是中文版 便于入门 ...

  9. Python之反射机制

    什么是反射? 1.有时我们要访问某个变量或是方法时并不知道到底有没有这个变量或方法,所以就要做些判断.判断是否存在字符串对应的变量及方法.2.我们知道访问变量时是不能加引号的,否则会被当成字符串处理. ...

  10. webpack——简单入门

    1.介绍 Webpack 是当下最热门的前端资源模块化管理和打包工具.它可以将许多松散的模块按照依赖和规则打包成符合生产环境部署的前端资源.还可以将按需加载的模块进行代码分隔,等到实际需要的时候再异步 ...