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 相关文章推荐
PHP5在Apache下的两种模式的安装
Sep 05 PHP
ASP和PHP都是可以删除自身的
Apr 09 PHP
解析PHPExcel使用的常用说明以及把PHPExcel整合进CI框架的介绍
Jun 24 PHP
php防止网站被刷新的方法汇总
Dec 01 PHP
合格的PHP程序员必备技能
Nov 13 PHP
PHP通过反射动态加载第三方类和获得类源码的实例
Nov 27 PHP
基于PHP代码实现中奖概率算法可用于刮刮卡、大转盘等抽奖算法
Dec 20 PHP
PHP版本常用的排序算法汇总
Dec 20 PHP
PHP按指定键值对二维数组进行排序的方法
Dec 22 PHP
PHP判断是手机端还是PC端 PHP判断是否是微信浏览器
Mar 15 PHP
Laravel中使用Queue的最基本操作教程
Dec 27 PHP
PHP sdk文档处理常用代码示例解析
Dec 09 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
PHP 七大优势分析
2009/06/23 PHP
PHP下通过exec获得计算机的唯一标识[CPU,网卡 MAC地址]
2011/06/09 PHP
php从数组中随机抽取一些元素的代码
2012/11/05 PHP
Ext.FormPanel 提交和 Ext.Ajax.request 异步提交函数的区别
2009/11/12 Javascript
两种WEB下的模态对话框 (asp.net或js的分别实现)
2009/12/02 Javascript
基于jquery.Jcrop的头像编辑器
2010/03/01 Javascript
使用jQuery重置(reset)表单的方法
2014/05/05 Javascript
jquery插件推荐 jquery.cookie
2014/11/09 Javascript
nodejs URL模块操作URL相关方法介绍
2015/03/03 NodeJs
浅谈jQuery中的事件
2015/03/23 Javascript
javascript模拟命名空间
2015/04/17 Javascript
jQuery实现鼠标悬停显示提示信息窗口的方法
2015/04/30 Javascript
javascript实现点击单选按钮链接转向对应网址的方法
2015/08/12 Javascript
javascript特效实现——当前时间和倒计时效果的简单实例
2016/07/20 Javascript
JavaScript中利用构造器函数模拟类的方法
2017/02/16 Javascript
JS仿QQ好友列表展开、收缩功能(第二篇)
2017/07/07 Javascript
nodejs实现解析xml字符串为对象的方法示例
2018/03/14 NodeJs
vue中的数据绑定原理的实现
2018/07/02 Javascript
微信小程序中使用 async/await的方法实例分析
2020/05/06 Javascript
js实现弹窗猜数字游戏
2020/11/26 Javascript
[02:04]2016国际邀请赛中国区预选赛VG.R晋级之路
2016/07/01 DOTA
使用matplotlib画散点图的方法
2018/05/25 Python
python生成以及打开json、csv和txt文件的实例
2018/11/16 Python
基于python框架Scrapy爬取自己的博客内容过程详解
2019/08/05 Python
基于Python的图像数据增强Data Augmentation解析
2019/08/13 Python
QML使用Python的函数过程解析
2019/09/26 Python
python3中的eval和exec的区别与联系
2019/10/10 Python
python 实现提取log文件中的关键句子,并进行统计分析
2019/12/24 Python
Python爬虫库BeautifulSoup的介绍与简单使用实例
2020/01/25 Python
Win10下安装并使用tensorflow-gpu1.8.0+python3.6全过程分析(显卡MX250+CUDA9.0+cudnn)
2020/02/17 Python
Python多线程多进程实例对比解析
2020/03/12 Python
PyQt5实现登录页面
2020/05/30 Python
HTML5本地存储localStorage、sessionStorage基本用法、遍历操作、异常处理等
2014/05/08 HTML / CSS
感恩教师主题班会
2015/08/12 职场文书
演讲开头怎么书写?
2019/08/06 职场文书
mysql sql常用语句大全
2022/06/21 MySQL