公司软件系统编程格式规范

2024-04-09 15:58:41

根据网络资源整理的公司软件系统编程规范，各开发人员予以执行此规范。

1. 前言

为确保系统源程序可读性，从而增强系统可维护性，兹制定下述编程规范，以规范系统各部分编程。系统继承的其它资源中的源程序也应按此规范作相应修改。

2. 试用范围

本文档将作为信息公司开发部（JAVA语言）软件项目系统开发的编程格式规范。在系统的编码、测试及维护过程中，要求严格遵守。

3. 命名规范

3.1 公共约定

Ø 命名指系统中对源文件名、方法、目录、包、数据库表名、数据库字段等的命名。

Ø 系统所用的命名都使用英文缩写来表达。

Ø 命名的组成方式为：前缀+{命名词素缩写}，前缀表达出命名的用途，如数据库表等。

Ø 命名的前缀由项目组确定。

Ø 除系统公共维护对象外的其他对象，命名全部用小写。一种方式用“_”作连接符，另一种方式是词素的第一个字母大写直接连接在一起。在本规范中，数据库名、数据库字段名采用第一种方式，其余采用第二种方式。

Ø 使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似 firstName，listAllUsers 或 CorporateCustomer 这样的名字，严禁使用汉语拼音及不相关单词命名。

Ø 采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。

Ø 尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，经理（manager）可缩写成mgr等，具体参看下表，严禁滥用缩写。

Ø 避免使用长名字（最好不超过 25 个字母）。

Ø 避免使用数字，但可用2代替to，用4代替for等，如：go2Jsp。

3.2 文件、包

Ø 文件名当与其类严格相同，所有单词首字母大写。

Ø 包名一般以项目或模块名命名，少用缩写和长名，一律小写。

Ø 基本包：com.czpost，所有包、文件都从属于此包。

包名按如下规则组成：

[基本包].[项目名].[模块名].[子模块名]...

com.czpost.eims

com.hepost.eims.until…

Ø 不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。

3.3 类、接口命名规范

Ø 所有单词首字母大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。

Ø 接口可带I前缀或able、ible、er等后缀。

3.4 方法命名规范

方法的命名应采用完整的英文描述符，大小写混合使用：所有中间单词的第一个字母大写。法名称的第一个单词常常采用一个有强烈动作色彩的动词。

取值类使用get前缀，设值类使用set前缀，判断类使用is(has)前缀。

例： getName()

方法参数建议顺序：(被操作者，操作内容，操作标志，其他⋯)

例：public void replace(String sourceStr,String oldStr, String newStr)

3.5 常量

采用完整的英文大写单词，在词与词之间用下划线连接，如：DEFAULT_VALUE

3.6 变量和参数

变量建议采用匈牙利命名法，词素规则见“公共约定”

ü 整型变量（包括int，short，long）：以 n 开头，例如：long nCredNum;

ü 浮点型变量（包括float，double）：以 f 开头，例如：double fTranAmt;

ü 字符变量：以 c 开头，例如：char cPageFlag;

ü 日期型变量：以d开头，例如：datedToday;

ü 布尔型变量：以is开头，例如：booleanisFlag;

ü 字符串变量：以 s 开头，例如：char sPageNo[2+1];

ü 全局变量：以g开头结合数据的类型，例如：char gsBankNo[10+1];

ü 静态变量：静态变量在文件中同样是全局变量，命名规则同全局变量。

ü 系统级变量：系统级变量同样是全局变量，以 ‘_’开头结合数据的类型。

例如：char _sBankNo[10+1] 没有‘g’。

临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。

3.7 组件/部件

应采用完整的英文描述符命名组件（接口部件），遵循匈牙利命名法则

如：btnOK，lblName。

ü 按钮变量 btn+Xxxxxxx 例如：btnSave, btn Exit, btnPrint等

ü 题标变量 lbl+Xxxxxxxx 例如：lblName, lblSex等

对象类型前缀

3.8 集合

一个集合，例如数组和矢量，应采用复数命名来表示队列中存放的对象类型。命名应采用完整的英文描述符，名字中所有非开头的单词的第一个字母应大写，适当使用集合缩写前缀。如：

Vector vProducts = new Vector(); //产品向量

Array aryUsers = new Array(); //用户列表

3.9 神秘的数

程序里经常会用到一些量，它是有特定的含义的，把神秘的数定义为一个常量。注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。例如50这个数，可以定义为一个名为NUM_OF_EMPLOYEES的常量来代替。

3.10 其他

命名时应使用复数来表示它们代表多值。如：orderItems。

3.11 异常类

异常类名由表示该异常类型的单词和Exception组成，如ActionException。

异常实例一般使用e、ex等，在多个异常时使用该异常名或简写加E，Ex等组成，如：

3.12 数组命名

数组应该总是用下面的方式来命名：

4. 数据库规范

设计数据库，主要使用PowerDesigner工具。设计物理数据模型（PDM文件），这时需要定义一个工程项目的数据字段域，定义字段域有一个好处就是以后设计数据表时，字段的类型可以选择用域中定义好的类型，更改了域的类型信息，表中与域引用相关的字段信息也相应改变，这样方便修改字段，也统一了字段类型和长度。定义好域之后，就可以设计数据表以及字段了。设计完表，可以选择导出的数据库类型，并生成建数据和建表的sql，再通过数据库连接工具执行sql语句，一个工程项目的数据库就建立好了。数据开发需要定义一套简明扼要的规范。

规范中应包括三个部分：编码的规范、字段类型长度的定义、表设计的特殊说明。

4.1 编码的规范

编码主要是要注意编码的前后缀，以便看到编码则知道是什么类型。给各个表与字段编码时，尽量保持编码的长度在20个字符以内，编码要求有一定意义，并且易懂。

ü 前缀与命名词素间用下划线分隔。

ü 命名由小写字母组成。

ü 命名词素如果由单一词组成，可用全拼；如果是多词组成，用缩写。缩写间用下划线。

Ø 库表：以‘t_’开头

Ø 视图：以‘v_’开头

Ø 库表索引：以‘t_’开头，以‘_idx’结尾

Ø 库表唯一索引：以‘t_’开头，以‘_uidx’结尾

Ø 主键pk_ [字符串or长整型] 例如：pk_company

Ø 外键fk_ [字符串or长整型] 例如：fk_employee

Ø 字符串 v 例如：vdetail

Ø 字符型 c 例如：ccolor

Ø 时间 d 例如：ddatetime

Ø 逻辑 b 例如：bisdeleted

Ø 整型 i 例如：itype

Ø 数字型（浮点行） n 例如：nprice

Ø 文本型 t 例如：tdescription

Ø 对象类型 o 例如：opicture

4.2 字段类型长度定义

ü 主键、外键如果是字符串行的话，建议用20个字符的长度。

ü 字符串的长度一般定义20、30、50、100、256、512、1024、2048、4096，超过4096个字符可以建议用文本类型来定义。

ü 定义字段的长度主要用于定义域的字段长度，从而规范表字段的类型及长度。

4.3 表设计的特殊说明

ü 表中的记录如果是假删除的话，则每个表需要统一的删除字段。

ü 另外，时间字段一般每一个表也要求出现，这样设计可以考虑目前或者以后做多线程访问的控制判断（即允许多读，但不允许多写），以后还有可能对一类表有固定必需字段的要求，这样的需求可以利用powerdesigner来统一添加。

ü 每一表建议只有主键非空，其余字段均可空，字段的非空判断交由程序来处理，不用数据库来判断。

5. 书写格式规范

严格要求书写格式是为了使程序整齐美观、易于阅读、风格统一，程序员对规范书写的必要性要有明确认识。建议源程序使用eclipse等工具开发，格式规范预先在工具中设置。

5.1 缩进

缩进建议以4个空格为单位。预处理语句、全局数据、标题、附加说明、函数说明、标号等均顶格书写。语句块的"{"、"}"配对对齐，并与其前一行对齐，语句块类的语句缩进建议每个"{"、"}"单独占一行，便于匹对。eclipse 中的默认方式是开始的"{"不是单独一行，建议更改成上述格式。

5.2 空格

原则上变量、类、常量数据和函数在其类型，修饰名称之间适当空格并据情况对齐。关键字原则上空一格，如：if ( ... ) 等。运算符的空格规定如下："::"、"->"、"["、"]"、"++"、"--"、"~"、"!"、"+"、"-"（指正负号）、"&"（引用）等几个运算符两边不加空格（其中单目运算符系指与操作数相连的一边），其它运算符（包括大多数二目运算符和三目运算符"?:"两边均加一空格，在作函数定义时还可据情况多空或不空格来对齐，但在函数实现时可以不用。","运算符只在其后空一格，需对齐时也可不空或多空格。不论是否有括号，对语句行后加的注释应用适当空格与语句隔开并尽可能对齐。个人认为此项可以依照个人习惯决定遵循与否。

5.3 对齐

原则上关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。另每一行的长度不应超过屏幕太多，必要时适当换行，换行时尽可能在","处或运算符处，换行后最好以运算符打头，并且以下各行均以该语句首行缩进，但该语句仍以首行的缩进为准，即如其下一行为“{”应与首行对齐。

变量定义最好通过添加空格或TAB键形成对齐，同一类型的变量最好放在一起。如下例所示：

5.4 空行

不得存在无规则的空行，比如说连续十个空行。程序文件结构各部分之间空一行，由于每个函数还要有函数说明注释，故通常只需空一行或不空，但对于没有函数说明的情况至少应再空一行。对自己写的函数，建议也加上“//------”做分隔。函数内部数据与代码之间应空至少一行，代码中适当处应以空行空开，建议在代码中出现变量声明时，在其前空一行。类中四个“p”之间至少空一行，在其中的数据与函数之间也应空行。

5.5 注释

注释是软件可读性的具体体现。程序注释量一般占程序编码量的20%，软件工程要求不少于20%。程序注释不能用抽象的语言，类似于"处理"、"循环"这样的计算机抽象语言，要精确表达出程序的处理说明。避免每行程序都使用注释，可以在一段程序的前面加一段注释，具有明确的处理逻辑。

注释必不可少，但也不应过多，不要被动的为写注释而写注释。以下是四种必要的注释：

ü 标题、附加说明。

ü 函数、类等的说明。对几乎每个函数都应有适当的说明，通常加在函数实现之前，在没有函数实现部分的情况下则加在函数原型前，其内容主要是函数的功能、目的、算法等说明，参数说明、返回值说明等，必要时还要有一些如特别的软硬件要求等说明。公用函数、公用类的声明必须由注解说明其使用方法和设计思路，当然选择恰当的命名格式能够帮助你把事情解释得更清楚。

ü 在代码不明晰或不可移植处必须有一定的说明。

ü 及少量的其它注释，如自定义变量的注释、代码书写时间等。

6. 代码文件风格

以java文件为例，所有的源代码文件都必须遵守如下的样式规则：

ü 文件生成

对于规范的派生类代码文件，尽量用工具如eclipse来生成文件格式，避免用手工制作的头文件/实现文件。

ü package/import

package 行要在 import 行之前，import 中标准的包名要在本地的包名之前，而且按照字母顺序排列。如果 import 行中包含了同一个包中的不同子目录，则应该用 * 来处理。

package hotlava.net.stats;

import java.io.*;

import java.util.Observable;

import hotlava.util.Application;

这里 java.io.* 使用来代替InputStream and OutputStream的。

ü 文件头部注释

文件头部注释主要是表明该文件的一些信息，是程序的总体说明，可以增强程序的可读性和可维护性。文件头部注释一般位于 package/imports 语句之后，Class 描述之前。要求至少写出文件名、创建者、创建时间和内容描述。其格式应该尽量约束如下：

*Title: 确定鼠标位置类

* Description: 确定鼠标当前在哪个作业栏位中并返回作业号

* @Copyright: Copyright (c) 2002

* @Company: HIT

* @author: rivershan

* @version: 1.0

接下来的是类的注释，一般是用来解释类的。

*A class representing a set of packet and byte counters

* It is observable to allow it to be watched, but only

* reports changes when the current set iscomplete

接下来是类定义，包含了在不同的行的 extends 和 implements

public class CounterSet

extends Observable

implements Cloneable

ü Class Fields

接下来是类的成员变量：

*Packet counters

protected int[] packets;

public 的成员变量必须生成文档（JavaDoc）。proceted、private和 package 定义的成员变量如果名字含义明确的话，可以没有注释。

ü 存取方法

接下来是类变量的存取的方法。它只是简单的用来将类的变量赋值获取值的话，可以简单的写在一行上。（个人认为尽量分行写）

*Get the counters

* @return an array containing the statistical data. This array has been

* freshly allocated and can be modified by the caller.

public int[] getPackets()

return copyArray(packets, offset);

public int[] getBytes()

return copyArray(bytes, offset);

public int[] getPackets()

return packets;

public void setPackets(int[] packets)

this.packets = packets;

其它的方法不要写在一行上

ü 构造函数

接下来是构造函数，它应该用递增的方式写（比如：参数多的写在后面）。

访问类型("public","private" 等.)和任何"static","final"或"synchronized"应该在一行中，并且方法和参数另写一行，这样可以使方法和参数更易读。

CounterSet(int size)

this.size = size;

ü 克隆方法

如果这个类是可以被克隆的，那么下一步就是 clone 方法：

CounterSet obj = (CounterSet)super.clone();

obj.packets = (int[])packets.clone();

obj.size = size;

catch(CloneNotSupportedException e)

throw new InternalError("UnexpectedCloneNotSUpportedException: "

+e.getMessage());

下面开始写类的方法：

*Set the packet counters

* (such as when restoring from a database)

protected final

void setArray(int[] r1, int[] r2, int[] r3, int[] r4)

throws IllegalArgumentException

// Ensure the arrays are of equal size

if (r1.length != r2.length || r1.length!= r3.length || r1.length

throw newIllegalArgumentException("Arrays must be of the same size";

System.arraycopy(r1, 0, r3, 0, r1.length);

System.arraycopy(r2, 0, r4, 0, r1.length);

ü toString 方法

无论如何，每一个类都应该定义 toString 方法：

String toString()

Stringretval = "CounterSet: ";

for (int i = 0; i < data.length();i++)

retval +=data.bytes.toString();

retval +=data.packets.toString();

如果main(String[]) 方法已经定义了, 那么它应该写在类的底部。

公司软件系统编程格式规范相关推荐

java的mysql语句规范_JAVA语言编程格式高级规范
作为一位开发人员,都要有严格的代码规范.为此我总结了一些代码规范案例. 目录 1. 前言 2. 试用范围 3. JAVA命名规范-- 3.1 公共约定 3.2 Java文件.包 3.3 类.接口命名 ...
sun公司java编程规范【转载】
java编程规范要学习的大致内容有如下部分,一个目录: Java编码规范 1 1.说明 3 1.1为什么要有编码规范 3 1.2版权声明 3 2.文件名(File Names) 3 2.1文件后缀(F ...
Apollo进阶课程 ⑧ | 高精地图的格式规范
目录高精地图规范格式分类 NDS格式规范 Open DRIVE格式规范原文链接:Apollo进阶课程 ⑧ | 高精地图的格式规范上周阿波君为大家详细介绍了「Apollo进阶课程⑦高精地图的采集与 ...
c,c++代码格式规范
c,c++代码格式规范第一章原则使代码易于管理的方法之一是增强代码一致性,让别人可以读懂你的代码是很重要的,保持统一编程风格意味着可以轻松根据"模式匹配"规则推断各种符号的含 ...
C/C++代码格式规范（一）
在写代码的时候,通常需要遵循一定的代码格式规范,本文针对自己做项目以及所接触的代码形式,同时也参考红帽rpm源码和谷歌代码规范,总结一下写代码时的编程规范,当然这不是硬性规定,许多地方可以根据自己的喜 ...
C语言编程的书写规则,关于C语言编程书写规范的规则和建议.doc
关于C语言编程书写规范的规则和建议关于C语言编程书写规范的规则和建议头文件头文件由三部分内容组成: 1.头文件开头处的版权和版本声明. 2.预处理块. 3.函数和类结构声明等. [规则]为了防止 ...
Java日志格式规范
Java日志格式规范文章目录 Java日志格式规范 **| 日志的作用** **| 撰写日志的要求** **日志的可读性:**日志时给人读的,不仅仅是让自己明白,也要让没有接触过我们源代码的其他程序 ...
Python：处理一些格式规范的文字
你要处理的大多数文字都是比较干净.格式规范的.格式规范的文字通常可以满足一些需求,不过究竟什么是"格式混乱",什么算"格式规范",确实因人而异. 通常,格式规范 ...
中文 Markdown 编写格式规范的命令行工具 lint-md
lint-md 用于检查中文 markdown 编写格式规范的命令行工具,基于 AST 开发,且方便集成 ci.Cli tool to lint your markdown file for Chin ...

最新文章

热门文章