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

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字段,不建议使用驼峰和中文作为数据表字段命名。

您可能感兴趣的文章:

  • 关于PHPDocument 代码注释规范的总结
  • PHP文件注释标记及规范小结
  • php 注释规范
  • PHP编码规范之注释和文件结构说明
  • PHP Document 代码注释规范
(0)

相关推荐

  • php 注释规范

    @access 使用范围:class,function,var,define,module 该标记用于指明关键字的存取权限:private.public或proteced @author 指明作者 @copyright 使用范围:class,function,var,define,module,use 指明版权信息 @deprecated 使用范围:class,function,var,define,module,constent,global,include 指明不用或者废弃的关键字 @exa

  • PHP编码规范之注释和文件结构说明

    文件结构 |――images |――include |――parameter |――config |――function |――index images存放图片文件,include中是系统是要引用的文件,一般在parameter中存放参数文件,config中存放配置文件,function中存放方法文件,如javascript的方法等,并按功能模块的分类,将各功能的类也放入其中 文件名 文件夹命名一般采用英文,长度一般不超过20个字符,命名采用小写字母.除特殊情况才使用中文拼音,一些常见的文件夹命

  • PHP Document 代码注释规范

    1. 什么是phpDocumentor ? PHPDocumentor 是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档.老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便. PHPDocumentor工作时,会扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释

  • PHP文件注释标记及规范小结

    PHP 注释标记 @access 使用范围:class,function,var,define,module 该标记用于指明关键字的存取权限:private.public或proteced @author 指明作者 @copyright 使用范围:class,function,var,define,module,use 指明版权信息 @deprecated 使用范围:class,function,var,define,module,constent,global,include 指明不用或者废弃

  • 关于PHPDocument 代码注释规范的总结

    1. 安装phpDocumentor(不推荐命令行安装)在http://manual.phpdoc.org/下载最新版本的PhpDoc放在web服务器目录下使得通过浏览器可以访问到点击files按钮,选择要处理的php文件或文件夹还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理.然后点击output按钮来选择生成文档的存放路径和格式.最后点击create,phpdocumentor就会自动开始生成文档了. 2.如何写PHP规范注释所有的文档标记都是在每一行的 * 后

  • JavaScript开发过程中规范commit msg意义详解

    目录 规范 commit msg 的意义 commitizen commitlint 安装依赖 添加 .commitlint.config.js 文件 配置 git hooks 总结一下: step 1: 安装依赖 step 2: 添加配置文件 git cz 的原理 规范 commit msg 的意义 规范化.格式化的 commit message 可以让我们更好的追踪需求的演进.回滚时能够快速的找到提交.最次也能让我们的仓库显的更专业. 团队如何规范 commit msg呢,靠宣讲.靠文档?当

  • GitLab Pipeline规范及流程触发详解

    目录 一.涉及概念 二.Pipeline流程触发 三.配置说明 四.共享Runner 一.涉及概念 名称 简述 Pipeline 流水线,用于组织构建CI/CD流程,实现了Pipeline As Code Stage 一条流水线是由多个阶段组成的,每个阶段一个stage,阶段按顺序执行 Job 每个阶段由多个Job组成,同个Stage下的多个Job可并行执行 CI/CD variables CI/CD过程中的环境变量 GitLab Runner 流水线任务执行者,执行定义好的脚步 二.Pipel

  • Python基础语法之变量与数据类型详解

    目录 一. 输出函数print 1.1 可以输出数字 1.2 可以输出字符串 1.3 可以输出表达式 1.4 可以输出至文件中 二. 变量与数据类型 2.1 整型 2.2 浮点型 2.3 字符串型 2.4 布尔型 3. 数据类型转换 3.1 int() 3.2 float() 3.3 str() 一. 输出函数print 在python中,print()是可以直接使用的输出函数,将数据输出到控制台上. 1. print函数的使用 1.1 可以输出数字 只要是数字都可以输出 # author: 爪

  • SpringBoot yaml语法与数据读取操作详解

    目录 yaml yaml语法规则 字面值表示方式: 数组表示方式: 对象数组格式: 对象数组缩略格式: 读取yaml数据 编写yaml文件 读取单一数据 读取二级数据 读取数组数据 读取服务器端口号 读取对象属性 封装全部数据到Environment对象 读取yaml引用类型属性数据 application.yml MyDataSource 读取数据 变量的引用 application.yml 读取数据 context-path @Autowired报错解决方案 yaml YAML是一种数据序列

  • Java 驼峰命名法详解(必看篇)

    标识符: Java对各种变量.方法和类等要素命名时使用的字符序列称为标识符 凡是自己可以起名字的地方都叫标识符 定义合法标识符的规则: 由26个英文字母大小写,0-9,_或$组成 数字不可以开头 不可以使用关键字和保留字,但是能包括关键字和保留字 Java中严格区分大小写,长度无限制 标识符不能包括空格 取名尽量做到"见名知意" 关于使用中文,Oracle 官网给出的文档是这样描述的: An identifier is an unlimited-length sequence of J

  • PHP 7.4 新语法之箭头函数实例详解

    短闭包,也叫做箭头函数,是一种用 php 编写的短函数.当向函数中传递闭包时,这个功能是非常有用的,比如使用 array_map 或是 array_filter函数时. 这就是它们看起来的样子: // Post 对象的集合 $posts = [/* - */]; $ids = array_map(fn($post) => $post->id, $posts); 而以前,你必须这样写: $ids = array_map(function ($post) { return $post->id

  • Java线程三种命名方法详解

    这篇文章主要介绍了Java线程三种命名方法详解,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 1.实例化一个线程对象 Thread t = new Thread(); t.setName("甲"); 2.实例化一个线程对象的同时,通过构造方法对线程进行命名 Thread(Runnable r, String name) Thread t = new Thread(() -> {}, "甲"); 3.使用自定义

  • Java基础语法之二维数组详解

    一.二维数组 进入正题之前.首先为了便于大家理解,我画了一个图: xx枪战游戏中, 我是一个刚刚注册账号的小白,系统送了我两把枪,此时,我的武器库只有这么一层(可以理解为一位数组,枪就是对应的数组中对应的元素) 经过艰苦卓绝的战斗,终于有了一笔钱,现在我打算配置好的游戏装备,我现在有了一个枪柜,它可以存放三层的枪械,每一层都可以放多把武器(这个就是二维数组,有多层,每层都是一个一维数组) 随着游戏时长和我的高超技术,获取游戏装备的效率越来越高了,一个枪柜已经存不下了,于是,我就有了多个枪柜(这个

  • TypeScript新语法之infer extends示例详解

    目录 正文 模式匹配 提取枚举的值的类型 总结 正文 我们知道,TypeScript 支持 infer 来提取类型的一部分,通过模式匹配的方式. 模式匹配 比如元组类型提取最后一个元素的类型: type Last<Arr extends unknown[]> = Arr extends [...infer rest,infer Ele] ? Ele : never; 比如函数提取返回值类型: type GetReturnType<Func extends Function> = F

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

    HP注释规范 注释在写代码的过程中非常重要,好的注释能让你的代码读起来更轻松,在写代码的时候一定要注意注释的规范. "php是一门及其容易入门的语言,刚入门的新手不到几分钟的时间可能就会用echo打印出一个hello world !但是他是真正的程序员吗?怎么来定义程序员呢?如果想真正成为一个程序员,那么就必须遵循一套程序书写规范," 我们经常编写一些函数,但是这些函数可能也只有自己能看得懂,甚至过一段时间自己也不认识自己写的了,那么怎么办呢?最好的办法当然是给给自己的代码加上注释.

随机推荐