Drupal/PHP/XHTML开发规范1.2

标签: drupal php xhtml | 发表时间:2010-11-28 20:36 | 作者:willietse 建江
出处:http://www.evilhtml.com/blog/6

*文中涉及XHTML/CSS部分,背景为黄底

前言

常言道,“没有规矩,不成方圆”。良好的编程风格与规范对开发者以及项目管理人员都是非常重要的。
当一个软件项目尝试着遵守公共一致的标准时,可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况。使新的参与者可以很快的适应环境,防止部分参与者出于节省时间的需要,自创一套风格并养成终生的习惯,导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下,也可以减少编码出错的机会。缺陷是由于每个人的标准不同,所以需要一段时间来适应和改变自己的编码风格,暂时性的降底了工作效率。从使项目长远健康的发展以及后期更高的团队工作效率来考虑暂时的工作效率降低是值得的,也是必须要经过的一个过程。标准不是项目成功的关键,但可以帮助我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。

第1章、排版规则

1.1、缩进

代码缩进使用2个空格,而不是tab键,因为在不同的编辑器查看代码时,tab键的显示出来的长度根是不一样的,虽然空格会增加文件的大小,这些误差是微不足道的。
在很多编辑器中,都可以设置将tab键设置为2个空格,如果你习惯使用tab键的话。

1.2、空格规则

空格应该在以下情况下使用:

  1. 关键字与(之间应该有1个空格,例:
    while ($user->uid > 0) {
    
  2. 函数名和(之间不应该有空格,例:
    function arg() {
    
  3. 一元操作符与其操作数之间不应该有空格,除非操作数是个单词,例:typeof。
  4. 每个在控制部分,例for语句中,“;”后必须跟一个空格。
  5. 每个,后应跟一个空格。

1.2.1、逻辑运算符前后都必须加空格,加一减一运算除外

// 正确
$a == $b;
// 错误
$a==$b;
$a ==$b;
// 正确
$a++;
$a--;
// 错误
$a ++;
$a --;

1.2.2、多个参数分隔时必须加空格

// 正确
$a, $ab, $c;
arg($a, $b, $c);
// 错误
$a,$ab,$c;
arg($a,$b,$c);

1.2.3、语法关键字后必须加空格

if, for, while, switch等关键字。
例:
// 正确
for ($a = 0;$ < 10; $a++);
// 错误
for($a = 0;$ < 10; $a++);

1.3、字符串和变量的连接规则

字符串与变量连接使用“.”,且在“.”左右都有1个空格,使用"自动转义变量时必须在变量前后加“{}”
// 正确
$result = 'file_' . $var;
$result = 'file_{var}';
// 错误
$result = 'file_'.$var;
$result = 'file_$var';

1.4、每行一个语句,除非这些语句有很密切的联系,否则每行只写一个语句。用空行来将逻辑相关的语句分隔开以提高程序的可读性。

正确
  $node_types = node_get_types('types', NULL, TRUE);

  foreach ($node_types as $type => $info) {
    //
  }
错误
  $node_types = node_get_types('types', NULL, TRUE);
  foreach ($node_types as $type => $info) {
    //
  }

1.5、关键字

if、for、do、while、case、switch、default等语句自占一行,且if、for、do、while等语句的执行语句部分无论多少都要有完整的括号{} 例:
正确
if (NULL == $arg) {
  return;
}
错误
if (NULL == $arg) return;

1.5.1、if

格式如下:
if (condition) {
  //
}

if (condition) {
  //
} else {
  
}

if (condition) {
  //
} else {
  //
}

1.5.2、for

格式如下:
for ($i = 0; $i < 1; $i++) {
  //
}

1.5.3、do

格式如下:
不像其他复合语句,do语句总是以“;”结束。
do {
  //
} while (condition);

1.5.4、do

格式如下:
switch (expression) {
  case expression:
    statements;
  default:
    statements;
}
每一组statements(除了default,应以break、return或者throw结尾。不要让它顺次往下执行。)

1.5.5、try

格式如下:
try {
  statements
} catch (variable) {
  statements
}

1.6、数据库

  • 查询语句中关键字部分应该大写。

1.7、CSS

  1. 规则主体部分缩进2个空格。
  2. 每个规则位于单独的行上。
  3. 规则之间空行。
格式如下:
#header .title a,
#header .title a:link,
#header .title a:visited,
#header .title a:active {
text-decoration: none;
color: #aaa;
}

#header .title a:hover {
color: #930;
}

第2章、命名规范

命名统一遵守Linux C命名规范,包括PHP、XHTML、CSS、JS。
变量名所有字母都小写,使用“_”作为每个词的分界(CSS中使用“-”,因为很多drupal生成的代码都用“-”(例如区块ID,通常为类似#block-vacation)。),变量名必须有一定的意义,使程序一目了然。
在项目中,相同意义的变量变量名应该尽量相同,例:drupal项目中$node表示节点,节点在很多地方都使用到,如果命名相同,一眼就可知道这是个节点,可以使用节点的相关函数操作,如要区分多个节点,则可以加上有意义的字母在前,例:$book_node、$color_node。

2.1、常量

PHP的常量应该全部使用大写字母,并使用_来正确的分隔字词。 常量使用模块名来作为前缀,这样个可以避免常用字词的冲突。例:你的模块名为test.module,那么常量名字应该如例TEST_USER。
define('TEST_CONFIRM_UID', 0);

2.2、全局变量

全局变量命名规则:$_模块名(主题名)_全局变量名 例:
// 错误
globe $records;
// 正确
globe $_test_records;

2.3、静态变量

静态变量使用前缀s,例:
$s_records;

2.4、临时变量

不要将在循环中频繁使用的临时变量如$i、$j等用于其他用途。

2.5、函数命名

函数名采用C GUN的惯例,所有字母使用小写字母,规则:模块名+_+函数名,要注意的是命名时不要与drupal的相关hook重名。

2.6、文件名命名

文件名应该都是小写的。例外情况就是文档文件,它们全部大写并且类型为txt文件。 例如:
LICENSE.txt
README.txt
INSTALL.txt

2.7、CSS命名

文件名应该都是小写的,且尽量使用英文字母,分隔符使用-。 一些常用文件名如下:
(1)页面结构类
容器: container
页头:header
内容:content/container
页面主体:main
页尾:footer
导航:nav
侧栏:sidebar
栏目:column
页面外围控制整体布局宽度:wrapper
(2)导航类
导航:nav
主导航:mainnav
子导航:subnav
顶导航:topnav
边导航:sidebar
左导航:leftsidebar
右导航:rightsidebar
位置导航: crumb
菜单:menu
子菜单:submenu
面包屑:breadcrumb(即页面所处位置导航提示)
(3)网页内容类
标题: title
摘要: summary
箭头: arrow
商标: label
网站标志: logo
转角/圆角: corner
横幅广告: banner
栏目: column
子菜单: subMenu
搜索: search
搜索框: searchBox
登录: login
工具条: toolbar
下拉: drop
标签页: tab
当前的: current
列表: list
滚动: scroll
服务: service
提示信息: msg
新闻: news
小技巧: tips
下载: download
栏目标题: title
热点: hot
加入: joinus
注册: regsiter
指南: guide
友情链接: friendlink
状态: status
版权: copyright
按钮: btn
合作伙伴: partner
投票: vote
头:header
内容:content/container
尾:footer
导航:nav
侧栏:sidebar
栏目:column
页面外围控制整体布局宽度:wrapper
左右中:left right center
登录条:loginbar
标志:logo
广告:banner
页面主体:main
热点:hot
新闻:news
下载:download
子导航:subnav
菜单:menu
子菜单:submenu
搜索:search
友情链接:friendlink
页脚:footer
版权:copyright
滚动:scroll
内容:content
标签页:tab
文章列表:list
提示信息:msg
小技巧:tips
栏目标题:title
加入:joinus
指南:guild
服务:service
注册:regsiter
状态:status
投票:vote
合作伙伴:partner

第3章、编程规范

系统统一使用时间戳time()作为时间标志,存入mysql时使用INT(10)类型写入。
引号使用单引号,只有当引号重叠时才使用双引号,这样每进程可以省几百K内存。
统一使用,禁止使用

3.1、数组定义规则

key、值必须使用单/双引号。
// 正确
array(
  'name' => 'myname',
  'type' => 'mytype'
);
// 错误
array(
  name => myname,
  type => mytype
);

3.2、不采用缺省方式测试变量/函数

// 正确
if ($user > 0) {
  //
}

if (arg(1) != '') {
  //
}
// 错误
if ($user) {
  //
}

if (arg(1)) {
  //
}

3.3、CSS

css能简写的使用简写,例如:padding: 10px;

3.3.1、隶属

隶属部分要标明,以免以后冲突,例如,某区块下的CSS,如下: #block-user .h3 { // }

3.3.2、定制reset.css

经常使用的css可定制为通用属性,使用的时候直接调用class,命名具备代表性,避免重复,例如:
.left {
  float: left;
}

.f10 {
  font-size: 10px;
}

3.3、文件结构规则

drupal模块开发规则如下(以模块名为book为例): 主模块(book.module)包含hook_help()、hook_init()、hook_menu()以及该模块的一些共用函数,如需要调用其他模块的函数(必须启用的核心模块除外),应先判断该模块是否开启(例:module_exists('book');)。
book.admin.inc(管理页面相关代码)、book.page.inc(用户操作所用代码),应该归类放置,使用hook_menu中“file”键指向。
模块中使用到的一些js插件,如jquery插件,应放在模块目录中js文件夹中。

3.4、数据库操作规则

  • 查询1条以及多条记录时,使用db_query_range()。
  • 每次查询如果可以都应该加上ORDER针对INDEX排序。

3.5、注释

注释文档遵循Doxygen注释样式,注释块语法如下(包括css、js):
/**
 * Implementation of hook_cron().
 */
function node_cron() {
  db_query('DELETE FROM {history} WHERE timestamp < %d', NODE_NEW_LIMIT);
}
注释块必须紧挨着放在函数前,中间不存在空行。 drupal能够理解下面所列的Doxygen构造体,具体构造体作用请参照Doxygen文档:
  • @mainpage
  • @file
  • @defgroup
  • @ingroup
  • @addtogroup
  • @param
  • @return
  • @link
  • @see
  • @{
  • @}

3.5.1、// $id$

“// $id$”用于追踪版本号以及最后修改的用户,以注释方式放在每个文件最前头(包括js、css等所有需要提交到版本库的文件)。当把代码提交到CVS(SVN),系统将会自动对这一标签进行解析和扩展,变成如下:
// $Id: node.module,v 1.947.2.29 2010/12/15 12:53:33 goba Exp $

第4章、编写安全的代码

4.1、处理用户输入输出

非drupal hook_form生成的表单(包括一些ajax)提交上的数据,应该进行安全过滤。以下列出drupal提供的一些过滤函数。
  • check_plain(HTML),转换为纯文本,将特定字符转换为HTML实体。
  • filter_xss(HTML),使用一组标签,检查和清理HTML
  • check_markup(HTML),使用过滤器(可以自定义)过滤
  • drupal_urlencode(URL),将特定字符编码为%0x
  • check_url(URL),清理url中有害协议,例如javascript:runevilJS()
通常在输出中,应该用t()函数,来过滤输出,以便支持drupal的多语言模块。

4.2、处理mysql语句

进行数据库的增删查改操作时,都要使用db_query()函数(drupal7使用方法有变动,具体请参照相关资料),表名必须使用大括号,这样在有数据库前缀的时候,可以自动判断。如下:
/**
 * Implementation of hook_cron().
 */
function node_cron() {
  db_query('DELETE FROM {history} WHERE timestamp < %d', NODE_NEW_LIMIT);
}

4.2.1、使用db_rewrite_sql()来保持私有数据的私有性

如果启用了节点访问模块对节点访问进行了权限控制,那么直接通过db_query()查出的数据是无法进行权限过滤的,这时候,需要用到db_rewrite_sql(),在一些节点数据的操作上,如果mysql语句没处理到权限部分,则必须使用该函数。例:
$result = db_query(db_rewrite_sql("SELECT DISTINCT b.* FROM {blocks} b LEFT JOIN {blocks_roles} r ON b.module = r.module AND b.delta = r.delta WHERE b.theme = '%s' AND b.status = 1 AND (r.rid IN (". db_placeholders($rids) .") OR r.rid IS NULL) ORDER BY b.region, b.weight, b.module", 'b', 'bid'), array_merge(array($theme_key), $rids));

第5章、其他重要杂项

  • 不到万不得已,不修改drupal核心代码,如有修改,应在开发文档中有记录。
  • 模块中HTML展示部分尽量都使用默认风格,例、table(theme('table', $header, $rows))、list(theme('item_list', $items))等,如特殊风格部分,HTML、CSS都应该写在模块中,而不是依赖主题,这样,在主题的切换中,就不会导致无法使用。
  • 所有的链接都必须使用l()函数,该函数会自动判断网站根目录位置,避免在网站迁移后有死链接。
  • 访问权限控制尽量捆绑在hook_menu上,不应该在函数内有过多的判断。

参考

PHPCMS开发文档
PHP程序编码规范(碎心竹整理版)
Pro Drupal Development 2nd Ed (2008)
Tags: 

相关 [drupal php xhtml] 推荐:

Drupal/PHP/XHTML开发规范1.2

- 建江 - willietse&#39;s blog
*文中涉及XHTML/CSS部分,背景为黄底. 常言道,“没有规矩,不成方圆”. 良好的编程风格与规范对开发者以及项目管理人员都是非常重要的. 当一个软件项目尝试着遵守公共一致的标准时,可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况. 使新的参与者可以很快的适应环境,防止部分参与者出于节省时间的需要,自创一套风格并养成终生的习惯,导致其它人在阅读时浪费过多的时间和精力.

Zotonic或能成为下一个Drupal

- Damon - Solidot
慕容鱼吐的新闻泡 写道 "Zotonic是一个开源内容管理系统,使用Erlang和PostgreSQL编写. Zotonic最新版本是0.6.0版,后台管理系统与Wordpress相似,但宣称比基于PHP的CMS系统快十倍. Zotonic还提供了一个类似Django的模板系统,并且支持websockets和comet.

xhEditor v1.1.9 发布,无障碍XHTML在线编辑器

- FPb - cnBeta.COM
感谢Yanis.Wang的投递. xhEditor是一个基于jQuery开发的简单迷你并且高效的无障碍可视化XHTML编辑器,基于网络访问并且兼容IE6,IE7,IE8,IE9,Firefox 3.0+,Opera 9.6+,Chrome 1.0+,Safari 3.22+.

分享20个 PSD 转换为 XHTML/CSS 的教程

- - 博客园_梦想天空
   在网上能搜罗到很多的PSD素材,有PSD按钮、PSD图标、PSD网站模板等等各种PSD界面素材. 那么如果把这些精美的PSD素材转换为 HTML/CSS 代码呢. 今天这篇文章要和大家分享的就是20个非常棒的把 PSD 转换为 XHTML/CSS 的教程. 梦想天空博客关注 前端开发技术,展示 HTML5和 CSS3应用,分享 jQuery插件,推荐优秀 网页设计案例.

PHP导出excel

- syeye - scofield PHP开发-SEO SEM
最近做一个项目,其中涉及到了数据导成excel的功能. 后来使用了 开源的 PHPExcel  http://phpexcel.codeplex.com/ 目前最新版是1.7.6. PHPExcel 可以生成 .xls 和 .xlsx (office2007). 比如设置 excel的title,keywords,description.

PHP框架 Yaf

- Le - 开源中国社区最新软件
Yaf是一个C语言编写的PHP框架,Yaf 的特点: 用C语言开发的PHP框架, 相比原生的PHP, 几乎不会带来额外的性能开销. 所有的框架类, 不需要编译, 在PHP启动的时候加载, 并常驻内存. 更短的内存周转周期, 提高内存利用率, 降低内存占用率. 支持全局和局部两种加载规则, 方便类库共享.

PHP RFC: 让PHP的foreach支持list

- 三马 - 风雪之隅
本文地址: http://www.laruence.com/2011/07/13/2110.html. 上个月, 终于算加入了PHP developer team, 一直以来最大的障碍就是语言, 现在想起来, 当年真应该更加认真努力的去学习英语.. 得到的第一个任务是: 解决一个feature request, 请求在allow foreach($array as list($a,$b).

PHP开发宝典-PHP基础

- - CSDN博客推荐文章
.