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 相关文章推荐
如何正确理解PHP的错误信息
Oct 09 PHP
php入门学习知识点七 PHP函数的基本应用
Jul 14 PHP
PHP垃圾回收机制引用计数器概念分析
Jun 24 PHP
修改ThinkPHP缓存为Memcache的方法
Jun 25 PHP
给WordPress的编辑后台添加提示框的代码实例分享
Dec 25 PHP
yii2控制器Controller Ajax操作示例
Jul 23 PHP
yii2使用GridView实现数据全选及批量删除按钮示例
Mar 01 PHP
php实现的后台表格分页功能示例
Oct 23 PHP
PHP长连接实现与使用方法详解
Feb 11 PHP
PHP实现获取ip地址的5种方法,以及插入用户登录日志操作示例
Feb 28 PHP
Laravel框架下载,安装及路由操作图文详解
Dec 04 PHP
详解阿里云视频直播PHP-SDK接入教程
Jul 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
PhpDocumentor 2安装以及生成API文档的方法
2014/05/21 PHP
php+ajax实现图片文件上传功能实例
2014/06/17 PHP
php数组函数array_walk用法示例
2016/05/26 PHP
快速保存网页中所有图片的方法
2006/06/23 Javascript
默认让页面的第一个控件选中的javascript代码
2009/12/26 Javascript
基于JQuery的cookie插件
2010/04/07 Javascript
日常收集整理的JavaScript常用函数方法
2015/12/10 Javascript
javascript 动态脚本添加的简单方法
2016/10/11 Javascript
javascript 缓冲运动框架的实现
2017/09/29 Javascript
解析Vue 2.5的Diff算法
2017/11/28 Javascript
JS中通过url动态获取图片大小的方法小结(两种方法)
2018/10/31 Javascript
vue-cli3单页构建大型项目方案
2020/04/07 Javascript
Postman参数化实现过程及原理解析
2020/08/13 Javascript
Vue实现计算器计算效果
2020/08/17 Javascript
小程序实现列表倒计时功能
2021/01/29 Javascript
[15:23]教你分分钟做大人:虚空假面
2014/10/30 DOTA
Python格式化css文件的方法
2015/03/10 Python
python如何去除字符串中不想要的字符
2020/07/05 Python
python实现决策树分类
2018/08/30 Python
Django Rest framework之认证的实现代码
2018/12/17 Python
python SQLAlchemy 中的Engine详解
2019/07/04 Python
python命名空间(namespace)简单介绍
2019/08/10 Python
对tensorflow中的strides参数使用详解
2020/01/04 Python
使用Tkinter制作信息提示框
2020/02/18 Python
Python反爬虫伪装浏览器进行爬虫
2020/02/28 Python
python能开发游戏吗
2020/06/11 Python
python破解同事的压缩包密码
2020/10/14 Python
css3利用transform变形结合事件完成扇形导航
2020/10/26 HTML / CSS
利用Canvas模仿百度贴吧客户端loading小球的方法示例
2017/08/13 HTML / CSS
7 For All Mankind官网:美国加州洛杉矶的高级牛仔服装品牌
2018/12/20 全球购物
使用useBean标志初始化BEAN时如何接受初始化参数
2012/02/11 面试题
美术专业个人自我评价
2014/01/18 职场文书
2014年小学元旦活动方案
2014/02/12 职场文书
社区端午节活动总结
2015/02/11 职场文书
自己搭建resnet18网络并加载torchvision自带权重的操作
2021/05/13 Python
VUE解决跨域问题Access to XMLHttpRequest at
2022/05/06 Vue.js