php

PHP命名规范

Posted by Eric on June 29, 2020

PHP变量命名规则

1、变量名必须以字母下划线_”开头,如”$_name”,”$name” ,”$name2”等,但是”$9name”是不对的。

2、变量名只能由字母、数字、以及“_”组成,还能包含汉字。如”$_qq”,”$qq308” ,”$my_apple”,“比如”$name我等”,但是”$name*”是不对的。

3、变量名不允许包含空格。当变量名由多个单词组成,建议使用“_”进行分隔(比如 $my_apple),俗称下划线法,或者以大写字母开头比如 ​$myApple,俗称骆驼式命名法(也称驼峰命名法)。

命名规范

先了解下

1、什么是 驼峰命名法?

2、大驼峰 与 小驼峰 的区别 ?

小驼峰法

变量一般用小驼峰法标识。驼峰法的意思是:除第一个单词之外,其他单词首字母大写。譬如

int myStudentCount;

变量myStudentCount第一个单词是全部小写,后面的单词首字母大写。

常用于函数名。

大驼峰法

相比小驼峰法,大驼峰法(即帕斯卡命名法)把第一个单词的首字母也大写了。常用于类名,属性,命名空间等。譬如

public class DataBaseUser;


  1. 类名:大驼峰命名法

  2. 类属性:

  • publicprotected类型的,小驼峰命名法;

  • private类型的,下划线(_)开头,小驼峰命名法;

  1. 类方法:
  • publicprotected类型的,小驼峰命名法;

  • private类型的,下划线(_)开头,小驼峰命名法;

  1. 类方法参数:小驼峰命名法;

  2. 函数:采用C GNU的惯例,所有的字母使用小写字母,使用下划线(_)分割单词;

  3. 函数参数:小驼峰命名法;

例如:

1
2
3
function some_bloody_function($userId, $userName) { 

}
  1. 常量:

所有字母都大写,使用下划线(_)分割单词;


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
  • 指明不用或者废弃的关键字

@example

  • 该标记用于解析一段文件内容,并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容

@const

  • 使用范围:define
  • 用来指明php中define的常量

@final

  • 使用范围:class,function,var
  • 指明关键字是一个最终的类、方法、属性,禁止派生、修改。

@filesource

  • 和example类似,只不过该标记将直接读取当前解析的php文件的内容并显示。

@global

  • 指明在此函数中引用的全局变量

@ingore

  • 用于在文档中忽略指定的关键字

@license

@link

  • 类似于license
  • 但还可以通过link指到文档中的任何一个关键字

@name

  • 为关键字指定一个别名。

@package

  • 使用范围:页面级别的-> define,function,include
  • 类级别的->class,var,methods
  • 用于逻辑上将一个或几个关键字分到一组。

@abstrcut

  • 说明当前类是一个抽象类

@param

  • 指明一个函数的参数

@return

  • 指明一个方法或函数的返回指

@static

  • 指明关建字是静态的。

@var

  • 指明变量类型

@version

  • 指明版本信息

@todo

  • 指明应该改进或没有实现的地方

@throws

  • 指明此函数可能抛出的错误异常,极其发生的情况
  • 普通的文档标记标记必须在每行的开头以@标记,除此之外,还有一种标记叫做inline tag,用{@}表示,具体包括以下几种:

{@link}

  • 用法同@link

{@source}

  • 显示一段函数或方法的内容

注释规范

a.注释必须是

1
2
3
/**
 * 注释内容
 */

的形式

b.对于引用了全局变量的函数,必须使用glboal标记。

c.对于变量,必须用var标记其类型(int,string,bool…)

d.函数必须通过param和return标记指明其参数和返回值

e.对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可

f.调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。

g.必要的地方使用非文档性注释,提高代码易读性。

h.描述性内容尽量简明扼要,尽可能使用短语而非句子。

i.全局变量,静态变量和常量必须用相应标记说明

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?php
/**
 * Sample File 2, phpDocumentor Quickstart
 *
 * This file demonstrates the rich information that can be included in
 * in-code documentation through DocBlocks and tags.
 * @author Greg Beaver <cellog@php.net>
 * @version 1.0
 * @package sample
 */
 
//PHP code
 
/**
 * A sample function docblock
 * @global string document the fact that this function uses $_myvar
 * @staticvar integer $staticvar this is actually what is returned
 * @param string $param1 name to declare
 * @param string $param2 value of the name
 * @return integer
 */
function firstFunc($param1, $param2 = 'optional') {
    static $staticvar = 7;
    global $_myvar;
    return $staticvar;
}
?>

phpDocumentor官方网站


YII框架的注释范例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
/**
 * CHttpSession提供了session级的数据管理和相关配置
 *
 * 开启session 调用 {@link open()};
 * 完成和发送session数据,调用 {@link close()};
 * 清除session,调用{@link destroy()}.
 *
 *
 * CHttpSession can be used like an array to set and get session data. For example,
 * <pre>
 *   $session=new CHttpSession;
 *   $session->open();
 *   $value1=$session['name1'];  // get session variable 'name1'
 *   $value2=$session['name2'];  // get session variable 'name2'
 *   foreach($session as $name=>$value) // traverse all session variables
 *   $session['name3']=$value3;  // set session variable 'name3'
 * </pre>
 *
 * The following configurations are available for session:
 * <ul>
 * <li>{@link setSessionID sessionID};</li>
 * <li>{@link setSessionName sessionName};</li>
 * <li>{@link autoStart};</li>
 * <li>{@link setSavePath savePath};</li>
 * <li>{@link setCookieParams cookieParams};</li>
 * <li>{@link setGCProbability gcProbability};</li>
 * <li>{@link setCookieMode cookieMode};</li>
 * <li>{@link setUseTransparentSessionID useTransparentSessionID};</li>
 * <li>{@link setTimeout timeout}.</li>
 * </ul>
 * See the corresponding setter and getter documentation for more information.
 * Note, these properties must be set before the session is started.
 *
 * CHttpSession can be extended to support customized session storage.
 * Override {@link openSession}, {@link closeSession}, {@link readSession},
 * {@link writeSession}, {@link destroySession} and {@link gcSession}
 * and set {@link useCustomStorage} to true.
 * Then, the session data will be stored and retrieved using the above methods.
 *
 * CHttpSession is a Web application component that can be accessed via
 * {@link CWebApplication::getSession()}.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id: CHttpSession.php 2497 2010-09-23 13:28:52Z mdomba $
 * @package system.web
 * @since 1.0
 */
class CHttpSession implements IteratorAggregate, ArrayAccess, Countable {
 
    /**
     * @var boolean whether the session should be automatically started when the session application component is initialized, defaults to true.
     */
    public $autoStart = true;
    private static $_instance = NULL;
  
    /**
     * Initializes the application component.
     * This method is required by IApplicationComponent and is invoked by application.
     */
    public function init() {
        if ($this->autoStart) {
            $this->open();
        }
 
         
        register_shutdown_function(array($this, 'close'));
    }
 
    /**
     * Returns a value indicating whether to use custom session storage.
     * This method should be overriden to return true if custom session storage handler should be used.
     * If returning true, make sure the methods {@link openSession}, {@link closeSession}, {@link readSession},
     * {@link writeSession}, {@link destroySession}, and {@link gcSession} are overridden in child
     * class, because they will be used as the callback handlers.
     * The default implementation always return false.
     * @return boolean whether to use custom storage.
     */
    public function getUseCustomStorage() {
        return false;
    }
 
    /**
     * Session open handler.
     * This method should be overridden if {@link useCustomStorage} is set true.
     * Do not call this method directly.
     * @param string $savePath session save path
     * @param string $sessionName session name
     * @return boolean whether session is opened successfully
     */
    public function openSession($savePath, $sessionName) {
        return true;
    }
 
    // 截取了一部分
  
}