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 相关文章推荐
ThinkPHP3.1新特性之对分组支持的改进与完善概述
Jun 19 PHP
深入浅出php socket编程
May 13 PHP
thinkphp3.2中Lite文件替换框架入口文件或应用入口文件的方法
May 21 PHP
全面解读PHP的人气开发框架Laravel
Oct 15 PHP
PHP函数func_num_args用法实例分析
Dec 07 PHP
PHP 使用 Imagick 裁切/生成缩略图/添加水印自动检测和处理 GIF
Feb 19 PHP
php中的抽象方法和抽象类
Feb 14 PHP
完美的php分页类
Oct 24 PHP
Laravel框架实现的rbac权限管理操作示例
Jan 16 PHP
Laravel 简单实现Ajax滚动加载示例
Oct 22 PHP
基于thinkphp6.0的success、error实现方法
Nov 05 PHP
swoole锁的机制代码实例讲解
Mar 04 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实现在线生成条形码示例分享(条形码生成器)
2013/12/30 PHP
20个2014年最优秀的PHP框架回顾
2014/10/22 PHP
php微信开发之音乐回复功能
2018/06/14 PHP
php使用fullcalendar日历插件详解
2019/03/06 PHP
菜单效果
2006/10/14 Javascript
JavaScript 检测浏览器和操作系统的脚本
2008/12/26 Javascript
JavaScript学习笔记之Cookie对象
2015/01/22 Javascript
JavaScript实现俄罗斯方块游戏过程分析及源码分享
2015/03/23 Javascript
javascript实现验证身份证号的有效性并提示
2015/04/30 Javascript
使用Node.js处理前端代码文件的编码问题
2016/02/16 Javascript
js捕捉键盘事件和按键键值的方法
2016/10/10 Javascript
Select2.js下拉框使用小结
2016/10/24 Javascript
jQuery手指滑动轮播效果
2016/12/22 Javascript
jQuery插件HighCharts绘制2D柱状图、折线图和饼图的组合图效果示例【附demo源码下载】
2017/03/09 Javascript
js实现拖拽上传图片功能
2017/08/01 Javascript
详解vue2 $watch要注意的问题
2017/09/08 Javascript
推荐一个基于Node.js的表单验证库
2019/02/15 Javascript
webpack 处理CSS资源的实现
2019/09/27 Javascript
[01:36]极致酷炫!TI9典藏宝瓶+撼地者至宝展示
2019/06/11 DOTA
Python求解平方根的方法
2015/03/11 Python
基于Python开发chrome插件的方法分析
2018/07/07 Python
python中bs4.BeautifulSoup的基本用法
2019/07/27 Python
Python中输入和输出(打印)数据实例方法
2019/10/13 Python
关于Flask项目无法使用公网IP访问的解决方式
2019/11/19 Python
Numpy中np.random.rand()和np.random.randn() 用法和区别详解
2020/10/23 Python
python装饰器代码深入讲解
2021/03/01 Python
详解前端HTML5几种存储方式的总结
2016/12/27 HTML / CSS
英语系本科生个人求职信
2013/09/21 职场文书
开会迟到检讨书
2014/02/03 职场文书
医德医魂心得体会
2014/09/11 职场文书
2014年优质护理服务工作总结
2014/11/14 职场文书
2014年酒店服务员工作总结
2014/12/08 职场文书
2015年银行信贷员工作总结
2015/05/19 职场文书
2015年街道办事处团委工作总结
2015/10/14 职场文书
2016年圣诞节义工活动总结
2016/04/01 职场文书
MySQL分区路径子分区再分区
2022/04/13 MySQL