代码规范说明.doc

代码开发规范对于新增代码或者修改的代码应按代码规范要求进行编写。一、通用规范1.1 Kconfig文件:格式：注释部分以#开头,空一格开始写注释内容。一级内容“config”顶头开始二级内容开头空白处为一个制表符，相当于8个空格三级内容开头空白处为一个制表符再加两个空格，即比二级内容缩进两个空格内容：help说明部分必须有，为第三级内容，需说明帮助信息，分段的内容需空一行，每块config间空一行。以文件系统fs下的Kconfig示例如下图1.1,代表一个空格，短横线所占一行代表一个空行:图1.1#File system configuration#-menu File systems-config EXT2_FStristate Second extended fs supporthelpExt2 is a standard Linux file system for hard disks.To compile this file system support as a module, choose M here: the module will be called ext2. Be aware however that the file system of your root partition (the one containing the directory /) cannot be compiled as a module, and so this could be dangerous.-If unsure, say Y.-config EXT2_FS_XATTRbool Ext2 extended attributesdepends on EXT2_FShelpExtended attributes are name:value pairs associatedwith inodes by the kernel or by users (see the attr(5) manual page, or visit for details).-If unsure, say N.1.2头文件.h和.c文件规范说明格式：制表符宽度相当于8个空格1.2.1文件首部注释文件首部的注释用于说明文件信息，可选项目包括：文件所属模块主要函数实现作者信息版权信息软件说明以上内容为可选信息，一个文件中不一定包含全部信息，由开发者根据重要性来确定。注释格式必须是块注释形式，即：以/*行开头，以*/行结束，中间每一行前面均加一个*，每行的*号在竖直方向是对齐排列的，内容部分距离行首的距离为4个字符，每段内容间空一行；作者信息部分若有多个作者，则每个作者单列一行，并与其他作者信息对齐；版权信息按时间段可分行说明，保持内部对齐。示例如下图1.2,其中方框代表一个空格:图1.2/*NSA Security-Enhanced Linux (SELinux) security module *This file contains the SELinux hook function implementations. *Authors: Stephen Smalley, * Chris Vance, *Copyright (C) 2001,2002 Networks Associates Technology, Inc.*Copyright (C) 2004-2005 Trusted Computer Solutions, Inc.* *This program is free software; you can redistribute it and/or *modify it under the terms of the GNU General Public License *version 2,as published by the Free Software Foundation.*/1.2.2代码注释新增或修改的代码重要部分可以添加注释。代码注释统一用/*和*/整块注释，注释内容与*间用空格隔开，若注释是多行，则采用类似首部注释的格式，每行注释前面都有一个*。(1) 函数定义注释注释可选项目：函数说明参数信息返回值信息使用信息对一个函数的注释，每项初始位置缩进要一致；可以缩进一个空格的或几个空格,内核代码一般缩进一个制表符。注释项分段时段与段间空一行，如下图所示为函数iunique的注释，代表空格：图1.3/*remove_inode_hash - remove an inode from the hash*inode: inode to unhash*Remove an inode from the superblock.*/void remove_inode_hash(struct inode *inode)图1.4/* 0 if the file is in use*= 0 if the file is not in use* 0 on failure*/asmlinkage long sys_fcount(int op, void _user *data)(2)代码块及单语句注释对整块代码进行的注释放在整块代码前面，如对函数说明注释放在函数定义前面一行；注释与被注释代码的缩进保持一致；对单独一条语句的注释可以放在语句后面，同一性质的注释最好保持对齐。图1.5#include /* for Unix socket types */图1.6if (dname_external(dentry) /* Both external: swap the pointers*/do_switch(target-d_, dentry-d_) ; else /* dentry:internal, target:external. Steal targets* storage and make target internal.*/dentry-d_ = target-d_;target-d_ = target-d_iname;1.2.3代码格式空行：代码块与代码块间至少空一行，同一类型的代码在不影响功能的情况下最好放在一块。如include语句，包含库文件中的头文件放在一起，包含非库文件的头文件放在一起，两部分中间空一行；不同函数定义间空一行。在函数内，简单变量声明放在一起，与其他语句间空行，复杂的变量如结构体、枚举类型的定义须占用多行时，单独作为一块，后面空一行；一般if语句、while语句、for语句等这些基本c语言语句类型后空一行，这些语句中嵌套的语句建议后面也空一行。goto语句到达的代码块，代码块名称顶头开始。缩进：第一级代码顶头开始，处于同一级的代码缩进保持一致。后一级别的代码比前一级别的代码缩进一个制表符。函数定义中参数分行列举时，后面的行应与第一个参数保持对齐；函数调用时出现参数需列多行的，也应与第一个参数保持对齐。数组、结构体、枚举类型等占用多行时缩进一个制表符。if、while、for、switch等语句的左花括号，与圆括号语句在同一行，与)用一个空格隔开，不再另起一行。空格：双目运算符前后空一格；函数多个参数用逗号隔开后空一格if、for、while、switch等基本语句中，关键词与左括号(间、右括号)与间有一个空格。图1.7for(p=p2;p-d_parent!=p;p=p-d_parent) if(p-d_parent=p1) return 1;二、kernel相关代码规范参照一通用规范部分的.h和.c文件规范说明三、glibc相关代码规范3.1头文件.h文件和.c文件规范3.1.1文件首部注释与通用规范1.2.1的差异在于：模块注释的中间行不需每行前面有*号，且注释内容的缩进为三个空格（距离行首）。此代码库中，文件首部注释部分除了对各个文件简单说明外，其他如软件版权信息基本不变。图3.1/*Copyright (C) 1995, 1997, 1998, 2000 Free Software Foundation, Inc.This file is part of the GNU C Library.Contributed by Ulrich Drepper , August 1995. The GNU C Library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. The GNU C Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with the GNU C Library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. */3.1.2代码注释(1)函数定义注释函数定义注释与首部注释格式相同，此库中对函数定义的注释较少，注释项目可参考通用规范1.2.2中(1)所述。注意：此库中函数定义格式与通用格式有不同，将返回值类型单独列在了函数名前面行，如下图所示。图3.2(2)代码块及单语句注释与通用规范1.2.2中(2)的风格一致，缩进不同处见下面的代码格式。3.1.3代码格式代码格式与通用规范1.2.3中所不同的地方在于：下一级代码相对于上一级代码的缩进是两个空格，if，while，for等语句的左花括号另起一行缩进，如上图中所示。/*Call kernel with additional two arguments the syscall requires. */intreboot (int howto)return ;if(k_dev!=dev)_set_errno (EINVAL);return -1;四、bibautil库代码规范参照通用规范五、procps库代码规范procps源码本身有些地方的风格不一，新增和修改部分进行风格统一。5.1头文件.h和.c文件规范说明5.1.1文件首部注释文件首部注释部分与通用规范1.2.1的主要差别在于每行注释内容与行首星号间只有一个空格。5.1.2代码注释(1)函数定义注释此库中对函数定义的注释较少，风格不一，现对于新增代码的函数定义注释统一参考通用规范1.2.2中(1)所述。注意：此库中函数内的所有都未单独一行开始，直接跟在语句后面。如下图所示：图5.1static int compare_two_procs(const void *a, const void *b)sort_node *tmp_list = sort_list;while(tmp_list)int result;result = (*tmp_list-sr)(*(const proc_t *const*)a, *(const proc_t *const*)b);if(result) return (tmp_list-reverse) ? -result : result;tmp_list = tmp_list-next;return 0; /* no conclusion */(2)代码块及单语句注释新增代码统一规定与通用规范1.2.2中(2)的风格一致，缩进不同处见下面的代码格式。(3)代码格式代码格式与通用规范1.2.3中所不同的地方在于：下一级代码相对于上一级代码的缩进是两个空格，如上图中所示。六、pam代码库规范说明pam代码库源码风格也不一致，新增或者修改的代码建议与修改处的源码风格保持一致；全新增加的代码参考下面规范。6.1头文件.h和.c文件规范说明6.1.1文件首部注释参考通用规范1.2.1,文件首部注释部分与通用规范1.2.1的主要差别在于每行注释内容与行首星号间不是八个空格而是一个空格。6.1.2代码注释(1)函数定义注释参考通用规范1.2.2中(1)函数定义注释，主要差别同样在于每行注释内容与行首星号间不是八个空格而是一个空格。(2)代码块和单语句注释参考通用规范1.2.2中(2)，(3)代码格式参考通用规范1.2.3，主要差别在于缩进大小不一定是一个制表符，与上下文保持一致，若无参考上下文则统一缩进四个空格。七、audit-module代码库规范说明audit-module代码库中.c和.h文件在缩进方面采用缩进一个制表符的风格很统一，在注释内容，空行与空格这类格式上可以参考通用规范1.2。Audit-module代码库中.l文件和.y文件函数定义注释以及代码块注释内容和格式可以参考通用规范1.2；.l文件中token标记对应的操作(即花括号内的代码)应根据内容调整对齐。八、coreutils代码库规范说明参考三glibc相关代码规范九、xen代码库规范说明十、policycoreutils代码库规范说明参考一通用规范十一、acl代码库规范说明参考一通用规范文件首部注释与通用规范1.2.1的差异在于：模块注释的中间行不需每行前面有*号，且注释内容的缩进为两个空格（距离行首）。图11.1/*File: parse.c(Linux Access Control List Management) Copyright (C) 1999, 2000Andreas Gruenbacher, This program is free software; you can redistribute it and/ormodify it under the terms of the GNU Lesser General PublicLicense as published by the Free Software Foundation; eitherversion 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.*/另一个差异在于函数定义时的返回值类型位置，应该参照图3.2中返回值类型格式。十二、audit代码库规范说明参考一通用规范，差异之处在于：文件首部注释应该将图1.2中两个空格变为一个空格，函数定义注释应将图1.3中注释行八个空格变为一个空格。十三、openssh代码库规范说明参考一通用规范，差异之处在于：文件首部注释部分应将图1.2中两个空格变为一个空格，函数定义注释部分也将图1.3中注释行八个空格变为一个空格，函数返回值类型格式应参照图3.2中返回值类型格式十四、shadow-utils代码库规范说明参考十二规范说明十五、smartcard代码库规范说明代码未修改十六、epass2000代码库规范说明参考十二规范说明十七、zhongwei.linux代码库规范说明参考一通用规范，差异之处在于：文件首部注释应该将图1.2中两个空格变为一个空格，函数定义注释应将图1.3中注释行八个空格变为一个空格。十八、yzw.anaconda代码库规范说明参考一通用规范，差异之处在于：缩进为四个空格。有效代码库：代码库所在目录：var/backup/serveroot/public-repo其下四个子目录：apps，kernel，policy，servicesapps中有效代码库：liping.openssh.gitliping.shadow-utils.git cps.gitliuyan.nfsark-policy.gityongbo.coreutils.gityongbo.policycoreutils.gityongbo.acl.gityzw.anaconda.gitkernel中有效代码库：yon