您当前的位置:首页 > 电脑百科 > 程序开发 > 语言 > php

PHP编程源代码常见注释规范讲解

时间:2019-09-06 09:50:43  来源:  作者:



说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。

/**
 * @version: V1.0
 * @author: pmdream
 * @className: user
 * @packageName: user
 * @description: 类注释
 * @data: 2019-9-5 11:20
 **/

方法注释

/**
* @author: pmdream
* @methodsName: addUser
* @description: 添加一个用户
* @param: xxxx
* @return: String
* @throws: 
**/

1.注释在写代码的过程中非常重要,好的注释能让你的代码读起来更轻松,在写代码的时候一定要注意注释的规范。

php是一门及其容易入门的语言,刚入门的新手不到几分钟的时间可能就会用echo打印出一个hello world !但是他是真正的程序员吗?怎么来定义程序员呢?如果想真正成为一个程序员,那么就必须遵循一套程序书写规范,”

我们经常编写一些函数,但是这些函数可能也只有自己能看得懂,甚至过一段时间自己也不认识自己写的了,那么怎么办呢?最好的办法当然是给给自己的代码加上注释。

我们可能熟悉很多注释的写法C pear PHP注释等等,但我们用到的主要还是# 和/**/。

#是一种简短的注释方法。可能你会用它去注释一个变量,或者调用的一个方法。/**/我们可能还在用它去注释掉一大段代码,但是怎么用它去标准的注释一个函数呢?

注释在写代码的过程中非常重要,好的注释能让你的代码读起来更轻松,在写代码的时候一定要注意注释的规范。

“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 2019-09-05
*/

文件头部模板

/** 
*这是一个什么文件 
* 
*此文件程序用来做什么的(详细说明,可选。)。 
* @author richard<e421083458@163.com> 
* @version $Id$ 
* @since 1.0 
*/

2.类的注释,类名及介绍

/**
* 类的介绍
* 
* 类的详细介绍(可选)
* @author 作者
* @version 版本号
* @date 2019-09-05
*/

 

/** 
* 类的介绍 
* 
* 类的详细介绍(可选。)。 
* @author richard<858560031@qq.com> 
* @since 1.0 
*/

3.函数的注释,函数的作用,参数介绍以及返回类型

/**
* 函数的含义说明
* 
* @access public 
* @author 作者
* @param mixed $arg1 参数一的说明 
* @param mixed $arg2 参数二的说明
* @return array 返回类型
* @date 2019-09-05
*/
函数

头部注释

/** 
* some_func 
* 函数的含义说明 
* 
* @access public 
* @param mixed $arg1 参数一的说明 
* @param mixed $arg2 参数二的说明 
* @param mixed $mixed 这是一个混合类型 
* @since 1.0 
* @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字段,不建议使用驼峰和中文作为数据表字段命名。



Tags:PHP   点击:()  评论:()
声明:本站部分内容来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,如有任何标注错误或版权侵犯请与我们联系,我们将及时更正、删除,谢谢。
▌相关评论
发表评论 共有条评论
用户名: 密码:
验证码: 匿名发表
▌相关推荐
PHP 8,PHP 的一个新的大版本,预计将于2020年12月3日发布,这意味着将不会有 PHP 7.5 版本。PHP8目前正处于非常活跃的开发阶段,所以在接下来的几个月里,情况可能会发生很大的变化...【详细内容】
2020-07-06   PHP  点击:(1)  评论:(0)  加入收藏
引言之前的文章我们已经讲过,在 PHP 类的创建过程中,使用 self 作为类本身的引用,使用 $this 作为类对象的引用。 而在 self 和 static 的使用上,有着细微的差别。特别是类继承...【详细内容】
2020-07-05   PHP  点击:(0)  评论:(0)  加入收藏
用任何编程语言来开发程序,都是为了让计算机干活,比如编写一篇文章,下载一首MP3等,而计算机干活的CPU只认识机器的指令,所以,尽管不同的编程语言差异极大,最后都得“翻译”成CPU可...【详细内容】
2020-06-29   PHP  点击:(1)  评论:(0)  加入收藏
对于php开发小白来说搭建一个php运行环境就是一道坎!因为要做php开发,搭建一个能够运行php网站的服务器环境是第一步,传统的php环境软件非常复杂,好在很多公司开发了一键搭建php...【详细内容】
2020-06-26   PHP  点击:(4)  评论:(0)  加入收藏
根据Alexa最新调查数据显示,服务器端编程语言的所有网站中,有79.0%使用PHP,使用PHP的所有网站中有52.8%使用了版本PHP7以上,当然稳定的版本PHP5依然有在所有php网站中占46.9%以上。...【详细内容】
2020-06-24   PHP  点击:(1)  评论:(0)  加入收藏
只想简单的做个带几个路由的服务,用 PHP 框架就有点大题小作了。Klein.php,这个轻量级的路由库,此时是一个不错的选择。Klein.php简介Klein.php,是 klein 组织在 Github 上开源...【详细内容】
2020-06-16   PHP  点击:(2)  评论:(0)  加入收藏
在这篇文章中,小编要给您推荐的是这款内置集成环境的软件,phpstudy。有些人一看到这个是国产的集成环境软件,心里就过不去,但是小编想说的是,不要因为他是国产软件就直接否定他,实...【详细内容】
2020-06-09   PHP  点击:(5)  评论:(0)  加入收藏
phpMyAdmin是一个非常受欢迎的基于web的MySQL数据库管理工具。它能够创建和删除数据库,创建/删除/修改表格,删除/编辑/新增字段,执行SQL脚本等,phpmyadmin也就相当于一个mysql...【详细内容】
2020-05-30   PHP  点击:(4)  评论:(0)  加入收藏
什么是连接池?顾名思义,连接池就是一堆预先创建好的连接,跟容器会有点像。连接池主要是在某种需要网络连接的服务,提前把连接建立好存起来,然后存放在一个池子里面,需要用到的时候...【详细内容】
2020-05-29   PHP  点击:(1)  评论:(0)  加入收藏
安装#进入安装目录cd /usr/local/bin#下载并安装sudo curl -s https://getcomposer.org/installer | sudo php#添加执行权限sudo chmod a+x composer.phar#加入全局命令mv...【详细内容】
2020-05-25   PHP  点击:(3)  评论:(0)  加入收藏
soap协议这个古老的通过wsdl文件通讯的协议,使用极其不方便,但是还有一些顽固的国企在使用,没办法,有一些需求必须跟他们对接接口,怎么办呢,在使用soap协议调用时候,php在这方面资...【详细内容】
2020-05-16   PHP  点击:(1)  评论:(0)  加入收藏
PHP与MySQL的连接有三种API接口,分别是:PHP的MySQL扩展 、PHP的mysqli扩展 、PHP数据对象(PDO) 。下面针对以上三种连接方式做下总结,以备在不同场景下选出最优方案。PHP的MySQ...【详细内容】
2020-05-14   PHP  点击:(4)  评论:(0)  加入收藏
1 尽量静态化如果一个方法能被静态,那就声明它为静态的,速度可提高1/4,甚至我测试的时候,这个提高了近三倍。当然了,这个测试方法需要在十万级以上次执行,效果才明显。其实静态方...【详细内容】
2020-05-13   PHP  点击:(2)  评论:(0)  加入收藏
1. 将MySQL安装压缩包解压,将解压后的文件夹移动到安装目录下,比如示例中将mysql-5.7.24-winx64.zip解压后的文件夹重命名为mysql,并移动到C:\Program Files下 2. 右击“此电脑...【详细内容】
2020-05-12   PHP  点击:(3)  评论:(0)  加入收藏
环境: 1、系统:Centos 7 2、Tengine 2.1.2 3、PHP 7.0 4、Mysql 5.7 5、supervisord 6、redis一、安装依赖包yum udateyum -y install gcc gcc-c++ autoconf automakeyum -y i...【详细内容】
2020-05-12   PHP  点击:(13)  评论:(0)  加入收藏
事务(Transaction)是访问并可能更新数据库中各种数据项的一个程序执行单元;事务的ACID特性事务应该具有4个属性:原子性、一致性、隔离性、持续性原子性(atomicity)。一个事务是...【详细内容】
2020-05-12   PHP  点击:(8)  评论:(0)  加入收藏
我从2012年开始学习如何使用HTML和CSS进行编码,自从我的编码之旅开始以来,PHP一直是我一直想学习的语言之一。 作为一个刚从JavaScript培训学校毕业的学生,我决定要重新尝试学...【详细内容】
2020-05-11   PHP  点击:(2)  评论:(0)  加入收藏
PHP-8将于今年年底发布,其最令人期待的功能之一就是JIT编译。让我们通过本文来看看这项功能对PHP脚本的速度有怎样的影响? 以下为译文:今年年底,PHP-8即将发布。虽然这个主版本...【详细内容】
2020-05-07   PHP  点击:(5)  评论:(0)  加入收藏
目录 概述 策略模式含义 策略模式的三种角色 策略模式实现步骤 策略模式设计代码实现 php7进阶到架构师相关阅读概述这是关于php进阶到架构之php7核心技术与实战学习的系列...【详细内容】
2020-05-07   PHP  点击:(1)  评论:(0)  加入收藏
我个人有一台阿里云的 ECS 服务器,平时用来测试的,前段时间 装过php7.2 是按照线上生产环境的步骤做的,只不过,生产环境不可能是一台一台手动安装的。我今天只是想把单台的安装...【详细内容】
2020-05-06   PHP  点击:(3)  评论:(0)  加入收藏
最新更新
栏目热门
栏目头条