PHP注释语法规范与命名规范详解篇


Posted in PHP onJanuary 21, 2018

HP注释规范

注释在写代码的过程中非常重要,好的注释能让你的代码读起来更轻松,在写代码的时候一定要注意注释的规范。

“php是一门及其容易入门的语言,刚入门的新手不到几分钟的时间可能就会用echo打印出一个hello world !但是他是真正的程序员吗?怎么来定义程序员呢?如果想真正成为一个程序员,那么就必须遵循一套程序书写规范,”

我们经常编写一些函数,但是这些函数可能也只有自己能看得懂,甚至过一段时间自己也不认识自己写的了,那么怎么办呢?最好的办法当然是给给自己的代码加上注释。

我们可能熟悉很多注释的写法C pear PHP注释等等,但我们用到的主要还是# 和/**/。

#是一种简短的注释方法。可能你会用它去注释一个变量,或者调用的一个方法。/**/我们可能还在用它去注释掉一大段代码,但是怎么用它去标准的注释一个函数呢?

/**
* @name 名字
* @abstract 申明变量/类/方法
* @access 指明这个变量、类、函数/方法的存取权限
* @author 函数作者的名字和邮箱地址

* @category 组织packages
* @copyright 指明版权信息
* @const 指明常量
* @deprecate 指明不推荐或者是废弃的信息
* @example 示例
* @exclude 指明当前的注释将不进行分析,不出现在文挡中
* @final 指明这是一个最终的类、方法、属性,禁止派生、修改。
* @global 指明在此函数中引用的全局变量
* @include 指明包含的文件的信息
* @link 定义在线连接
* @module 定义归属的模块信息
* @modulegroup 定义归属的模块组
* @package 定义归属的包的信息
* @param 定义函数或者方法的参数信息
* @return 定义函数或者方法的返回信息
* @see 定义需要参考的函数、变量,并加入相应的超级连接。
* @since 指明该api函数或者方法是从哪个版本开始引入的
* @static 指明变量、类、函数是静态的。
* @throws 指明此函数可能抛出的错误异常,极其发生的情况
* @todo 指明应该改进或没有实现的地方
* @var 定义说明变量/属性。
* @version 定义版本信息
*/

注释的信息很全面,可能有很多我们用不到,红色部分是我们经常用到的。

示例:php里面常见的几种注释方式:

1.文件的注释,介绍文件名,功能以及作者版本号等信息

/**
* 文件名简单介绍
* 
* 文件功能
* @author 作者
* @version 版本号
* @date 2020-02-02
*/

文件头部模板

/** 
*这是一个什么文件 
* 
*此文件程序用来做什么的(详细说明,可选。)。 
* @author   richard<e421083458@163.com> 
* @version   $Id$ 
* @since    1.0 
*/

2.类的注释,类名及介绍

/**
* 类的介绍
* 
* 类的详细介绍(可选)
* @author 作者
* @version 版本号
* @date 2020-02-02
*/
/** 
* 类的介绍 
* 
* 类的详细介绍(可选。)。 
* @author     richard<e421083458@163.com> 
* @since     1.0 
*/ 
class Test  
{ 
}

3.函数的注释,函数的作用,参数介绍以及返回类型

/**
* 函数的含义说明
* 
* @access public 
* @author 作者
* @param mixed $arg1 参数一的说明 
* @param mixed $arg2 参数二的说明
* @return array 返回类型
* @date 2020-02-02
*/

函数头部注释

/** 
* some_func 
* 函数的含义说明 
* 
* @access public 
* @param mixed $arg1 参数一的说明 
* @param mixed $arg2 参数二的说明 
* @param mixed $mixed 这是一个混合类型 
* @since 1.0 
* @return array 
*/ 
public function thisIsFunction($string, $integer, $mixed) {return array();}

程序代码注释

1. 注释的原则是将问题解释清楚,并不是越多越好。

2. 若干语句作为一个逻辑代码块,这个块的注释可以使用/* */方式。

3. 具体到某一个语句的注释,可以使用行尾注释://。

/* 生成配置文件、数据文件。*/ 
 
$this->setConfig(); 
$this->createConfigFile(); //创建配置文件 
$this->clearCache();     // 清除缓存文件 
$this->createDataFiles();  // 生成数据文件 
$this->prepareProxys(); 
$this->restart();

PHP命名规范

1.目录和文件

目录使用小写+下划线
类库,函数文件统一以.php为后缀
类的文件名均以命名空间定义,并且命名空间的路径和类库文件所在路径一致
类文件采用驼峰法命名(首字母大写),其他文件采用小写+下划线命名
类名和类文件名保持一致,统一采用驼峰法(首字母大写)

2.函数和类,属性命名

类的命名采用驼峰法(首字母大写),例如 User、UserType,默认不需要添加后缀,例如UserController应该直接命名为User
函数的命名使用小写字母和下划线(小写字母开头)的方式,例如 get_client_ip
方法的命名使用驼峰法(首字母小写),例如 getUserName(如果方法有返回值,那么目前习惯上将首字母用小写的属性类型,如s(string),i(int),f(float),b(boolean),a(array)等)
属性的命名使用驼峰法(首字母小写),例如 tableName、instance(目前习惯上将首字母用小写的属性类型,如s(string),i(int),f(float),b(boolean),a(array)等)
以双下划线“__”打头的函数或方法作为魔法方法,例如 __call 和 __autoload

3.常量和配置

常量以大写字母和下划线命名,例如 APP_PATH和 THINK_PATH
配置参数以小写字母和下划线命名,例如 url_route_on 和url_convert

4.数据表盒字段

数据表和字段采用小写加下划线方式命名,并注意字段名不要以下划线开头,例如 think_user 表和 user_name字段,不建议使用驼峰和中文作为数据表字段命名。

PHP 相关文章推荐
我的论坛源代码(一)
Oct 09 PHP
php开发文档 会员收费1期
Aug 14 PHP
PHP实现根据浏览器跳转不同语言页面代码
Aug 02 PHP
PHP删除数组中空值的方法介绍
Apr 14 PHP
PHP中使用php5-ffmpeg撷取视频图片实例
Jan 07 PHP
php ucwords() 函数将字符串中每个单词的首字符转换为大写(实现代码)
May 12 PHP
CodeIgniter集成smarty的方法详解
May 26 PHP
php面向对象之反射功能与用法分析
Mar 29 PHP
PHP实现打包下载文件的方法示例
Oct 07 PHP
Laravel6.2中用于用户登录的新密码确认流程详解
Oct 16 PHP
PHP与Web页面交互操作实例分析
Jun 02 PHP
关于PHP数组迭代器的使用方法实例
Nov 17 PHP
php nginx 实时输出的简单实现方法
Jan 21 #PHP
Lumen timezone 时区设置方法(慢了8个小时)
Jan 20 #PHP
PHP Class SoapClient not found解决方法
Jan 20 #PHP
tp5(thinkPHP5)操作mongoDB数据库的方法
Jan 20 #PHP
php实现的mongoDB单例模式操作类
Jan 20 #PHP
PHP实现合并两个排序链表的方法
Jan 19 #PHP
php利用ob_start()清除输出和选择性输出的方法
Jan 18 #PHP
You might like
无线电波是什么?它是怎样传输的?
2021/03/01 无线电
php通过array_merge()函数合并关联和非关联数组的方法
2015/03/18 PHP
PHP5.2中PDO的简单使用方法
2016/03/25 PHP
被jQuery折腾得半死,揭秘为何jQuery为何在IE/Firefox下均无法使用
2010/01/22 Javascript
基于jQuery判断两个元素是否有重叠部分的代码
2012/07/25 Javascript
jQuery的3种请求方式$.post,$.get,$.getJSON
2014/03/28 Javascript
JavaScript获取Url里的参数
2014/12/18 Javascript
js实现仿qq消息的弹出窗效果
2016/01/06 Javascript
jquery ajax结合thinkphp的getjson实现跨域的方法
2016/06/06 Javascript
为jQuery-easyui的tab组件添加右键菜单功能的简单实例
2016/10/10 Javascript
Angularjs的Controller间通信机制实例分析
2016/11/07 Javascript
原生js实现可爱糖果数字时间特效
2016/12/30 Javascript
React Router基础使用
2017/01/17 Javascript
又一款MVVM组件 构建自己的Vue组件(2)
2017/03/13 Javascript
详解Node中导入模块require和import的区别
2017/08/11 Javascript
详解VUE Element-UI多级菜单动态渲染的组件
2019/04/25 Javascript
node.js使用mongoose操作数据库实现购物车的增、删、改、查功能示例
2019/12/23 Javascript
深入了解JavaScript词法作用域
2020/07/29 Javascript
nuxt.js服务端渲染中axios和proxy代理的配置操作
2020/11/06 Javascript
Python中的Matplotlib模块入门教程
2015/04/15 Python
通过实例浅析Python对比C语言的编程思想差异
2015/08/30 Python
python迭代dict的key和value的方法
2018/07/06 Python
将自己的数据集制作成TFRecord格式教程
2020/02/17 Python
基于HTML5陀螺仪实现ofo首页眼睛移动效果的示例
2017/07/31 HTML / CSS
Foreo国际站:Foreo International
2018/10/29 全球购物
奥地利时尚、美容、玩具和家居之家:Kastner & Öhler
2020/04/26 全球购物
学校介绍信范文
2014/01/14 职场文书
党员一帮一活动总结
2014/07/08 职场文书
2015元旦联欢晚会结束语
2014/12/14 职场文书
企业党建工作总结2015
2015/05/26 职场文书
遗愿清单观后感
2015/06/09 职场文书
我的法兰西岁月观后感
2015/06/09 职场文书
昆虫记读书笔记
2015/06/26 职场文书
详解jQuery的核心函数和事件处理
2022/02/18 jQuery
Python PIL按比例裁剪图片
2022/05/11 Python
zabbix配置nginx监控的实现
2022/05/25 Servers