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 相关文章推荐
JAVA/JSP学习系列之二
Oct 09 PHP
PHP采集相关教程之一 CURL函数库
Feb 15 PHP
Mysql数据库操作类( 1127版,提供源码下载 )
Dec 02 PHP
php缩小png图片不损失透明色的解决方法
Dec 25 PHP
php实现粘贴截图并完成上传功能
May 17 PHP
php无序树实现方法
Jul 28 PHP
学习php设计模式 php实现原型模式(prototype)
Dec 07 PHP
Yii实现复选框批量操作实例代码
Mar 15 PHP
详解php语言最牛掰的Laravel框架
Nov 20 PHP
在php的yii2框架中整合hbase库的方法
Sep 20 PHP
php微信分享到朋友圈、QQ、朋友、微博
Feb 18 PHP
is_file和file_exists效率比较
Mar 14 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下关于中英数字混排的字符串分割问题
2010/04/06 PHP
PHP下SSL加密解密、验证、签名方法(很简单)
2020/06/28 PHP
PHP策略模式定义与用法示例
2017/07/27 PHP
laravel5使用freetds连接sql server的方法
2018/12/07 PHP
JS对象与JSON格式数据相互转换
2012/02/20 Javascript
基于jquery自己写tab滑动门(通用版)
2012/10/30 Javascript
基于jQuery实现模拟页面加载进度条
2013/04/01 Javascript
js调用后台servlet方法实例
2013/06/09 Javascript
实现前后端数据交互方法汇总
2015/04/07 Javascript
关于javascript事件响应的基础语法总结(必看篇)
2016/12/26 Javascript
基于JQuery的购物车添加删除以及结算功能示例
2017/03/08 Javascript
JavaScript 值类型和引用类型的初次研究(推荐)
2017/07/19 Javascript
JS实现简易换图时钟功能分析
2018/01/04 Javascript
JS实现的小火箭发射动画效果示例
2018/12/08 Javascript
VUE+elementui组件在table-cell单元格中绘制微型echarts图
2020/04/20 Javascript
Jquery $.map使用方法实例详解
2020/09/01 jQuery
[47:20]DAC2018 4.4 淘汰赛 Optic vs Mineski 第一场
2018/04/05 DOTA
[04:16]完美世界DOTA2联赛PWL S2 集锦第一期
2020/11/23 DOTA
深入理解python中的atexit模块
2017/03/07 Python
Python定时器实例代码
2017/11/01 Python
Django 迁移、操作数据库的方法
2019/08/02 Python
python如何编写win程序
2020/06/08 Python
详解在Python中使用Torchmoji将文本转换为表情符号
2020/07/27 Python
python生成xml时规定dtd实例方法
2020/09/21 Python
会走动的图形html5时钟示例
2014/04/27 HTML / CSS
外企C语言笔试题
2013/11/10 面试题
成都思必达公司C#程序员招聘面试题
2013/06/26 面试题
公司培训欢迎词
2014/01/10 职场文书
有趣的广告词
2014/03/18 职场文书
《第一朵杏花》教学反思
2014/04/16 职场文书
2014高三学生考试作弊检讨书
2014/12/14 职场文书
小学国庆节活动总结
2015/03/23 职场文书
大学生入党群众意见书
2015/06/02 职场文书
第一军规观后感
2015/06/12 职场文书
《圆明园的毁灭》教学反思
2016/02/16 职场文书
JavaScript的Set数据结构详解
2022/02/18 Javascript