【软件工程】软件设计中的通用编码规范

前言

总结软件工程中的一些通用编码规范。

提示：以下内容参考chat回答

一、通用编码规范

1. 命名规范

• 变量、函数、类和文件名应该简明易懂，使用英文单词或单词缩写，并使用下划线或驼峰命名法。
• 变量名应该使用名词，函数名应该使用动词，类名应该使用名词或名词短语，文件名应该使用有意义的名称。
• 举例：

first_name = "John"
last_name = "Doe"

（1）使用驼峰命名法

def calculateSalary():
    pass
    
class CustomerOrder:
    pass

（2）使用有意义的文件名

customer_order.py

2. 格式化规范

• 代码行长度应该不超过80个字符。
• 使用一致的缩进和空格以使代码更易于阅读
• 在两个操作符之间使用空格，例如赋值、比较和算术操作符
• 举例：
  （1）代码行长度不超过80个字符

def calculate_discount(price, discount_percentage):
    return price * discount_percentage / 100

（2）使用一致的缩进和空格

if user_age < 18:
    print("You are a minor")
else:
    print("You are an adult")

（3）在赋值、比较和算术操作符之间使用空格

age = 25
if age == 18:
    print("You are a young adult")

3. 注释规范

• 注释应该清晰、有意义，并解释代码的目的，而不是显而易见的东西。
• 注释应该写在需要注释的代码上面，并在需要的地方使用空行分隔。
• 举例：

def calculate_discount(price, discount_percentage):

（1）计算折扣后的价格

return price * discount_percentage / 100

（2）两行空行分隔

class CustomerOrder:

4. 函数的长度规范

• 尽量保持函数的短小精悍，以提高代码的可读性和可维护性。
• 函数应该只做一件明确的事情，如果函数过于复杂，则需要将其拆分成较小的函数。
• 举例：

def process_customer_order(customer, order_items):

（1）检查客户地址的有效性

 check_address(customer.address)

（2）检查订单是否有足够的库存

for item in order_items:
    check_stock(item.product_code, item.quantity)

（3）保存订单

 save_order(customer, order_items)

（4）较短函数

def check_address(address):

（5）检查地址的有效性

def check_stock(product_code, quantity):

（6）检查库存是否充足

    pass

def save_order(customer, order_items):

（7） 保存订单

5. 错误处理规范

• 带有适当错误处理的代码不仅更可靠，而且更容易调试。
• 尽可能使用异常处理来处理错误。
• 举例：

（1）试图打开一个不存在的文件

try with open("non_existing_file.txt", "r") as f:
    content = f.read()

（2）捕获文件不存在的异常

except FileNotFoundError:
    print("File not found")

6. 冗余代码规范

• 尽管DRY（不要重复自己）原则已经很出名了，但它仍然是一个很好的编程实践，可以减少冗余代码和错误数量。
• 尽可能使用现有的代码或函数，而不是编写新的代码。
• 举例：

if user_age < 18:
    print("You are a minor")
else:
    print("You are an adult")

不需要重复代码

if is_minor(user_age):
    print("You are a minor")
else:
    print("You are an adult")

可以使用函数

def is_minor(age):
    return age < 18

7. 通用开发模式规范

• 在编程实践中尽量使用通用的设计模式，以提高代码的可维护性。
• 使用面向对象编程的原则如高内聚、低耦合等。
• 举例：

class Customer:
    def __init__(self, name, email, phone):
        self.name = name
        self.email = email
        self.phone = phone

class Order:
    def __init__(self, customer, items):
        self.customer = customer
        self.items = items

二、逸哥总结的编码规范

以下编码规范来自于大佬张逸的文档资料。

1.前言

1.1编写目的

为了保证编写出的程序都符合相同的规范，保证一致性、统一性而建立的程序编码规范。

编码规范对于程序员而言尤为重要，有以下几个原因：

1. 一个软件的生命周期中，80%的花费在于维护。
2. 几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。
3. 编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码 。
   每个软件开发人员都必须遵守统一的编码规范。

1.2适用范围

本规范适用于《从零开始编写自己的C# 框架》的开发。

1.3基本要求

尽量使代码简单直白。

2.命名规范

2.1字母大小写约定

2.1.1说明
表达清晰的命名规范是程序规划的核心，如果规范的命名能清晰的表达出相应的功能，就可以让人“望文知意”，提高开发效率和系统的可维护性。反之，如果命名不能表达其含义，例如“aaa”、“bbb ()”，那么将适得其反。
2.1.2Pascal风格
包含一到多个单词，每一个单词第一个字母大写，其余字母均小写。例如：HelloWorld、SetName等。
2.1.3Camel风格
包含一到多个单词，第一个单词首字母小写，其余单词首字母大写。例如：name、productId等。

2.2标识符的大小写规则

（1）除了参数与变量外，所有命名空间名称、类、函数、接口、属性等名称的命名，使用 Pascal 风格。
（2）参数与变量的命名，使用Camel风格。

2.3通用命名约定

约定的是如何选择最适当的名称，这些准则适用于所有标识符命名。

2.3.1选择名称

(1)请选择易读的英文名称
例如，英文 Order的意思为规则、次序、订购等，如果用在排序列中就不是很合适，用来表示订单则更具可读性。
可读性比详细描述更重要，比如表示坐标名称ScreenX就比ScreenHorizontally 更具可读性。

(2)除下划线外，不要使用连字符或任何其他非字母数字字符
在数据库表字段名称设计时，与其他表字段有关联时，适当的使用表名+下横线+字段名，可以更清晰的表现出该字段与关联表对应字段的关系。
比如产品分类表ProductClass有字段Id与Name，那么产品表绑定这两个字段的名称可命名为ProductClass_Id与ProductClass_Name，这样在查看产品表时就可以清晰的知道这两个字段与分类表的关系。

(3)避免使用与常用编程语言的关键字冲突的标识符

(4)变量和方法参数使用Camel 风格
例如：

string productName = "";
int number=0;
string sqlString="";
double averageScore=0.0;
Users users=new Users();
Users model=new Users();
Users userModel=new Users();
const string const_String = "";（不同公司有不同的约定，具体根据自己公司情况设置而定）

	Private string GetProductName(int id)
{
		return "";
}

(5)不要使用成员属性作为成员变量的前缀（其他变量命名也一样）
例如： 不要像Users m_users;这样定义成员变量，可以使用第4点的设置。

2.3.2字母缩写词

(1)通常，不应使用缩写

(2)除非这种缩写已广泛接受，又或者团队当中大家都认可一种缩写
例如，使用 OnButtonClick，如果团队中普遍认可OnBtnClick这种写法也是可以的。

2.4命名空间命名

命名空间命名采用Pascal风格，取名的一般规则如下。
CompanyName. ProjectName （公司名称.项目名称）
例如：

Microsoft.Office

需要用复数时，请使用复数。
例如，使用System.Collections而不是System.Collection。
需要缩写时，不需要加复数。
例如：使用System.IO而不是System.IOs。

2.5类、结构和接口命名

(1)按照 Pascal 大小写格式，使用名词或名词短语为类、接口和值类型命名

(2)接口命名以字母 I 为前缀
例如：IComponent

(3)派生类的末尾使用基类名称
例如，从 Stream 继承的 Framework 类型以 Stream 结尾，从 Exception 继承的类型以 Exception 结尾。

2.6逻辑层类命名

按照 Pascal 大小写格式，使用名词或名词短语命名，并加上后缀Logic

2.7文件夹命名

文件夹以功能模块名称，按照 Pascal 大小写格式命名。
比如后端管理功能以及权限相关功能，全部放到Systems文件夹里。

3.注释规范

3.1模块（类）注释规范

模块开始必须以以下形式书写模块注释：

///<summary>
	///模块编号：<模块编号，可以引用系统设计中的模块编号>
	///作用：<对此类的描述，可以引用系统设计中的描述>
	///作者：作者中文名
	///编写日期：<模块创建日期，格式：YYYY-MM-DD>
	///</summary>
	
如果模块有修改，则每次修改必须添加以下注释：
	///<summary>
	///Log编号：<Log编号,从1开始一次增加>
	///修改描述：<对此修改的描述>
	///作者：修改者中文名
	///修改日期：<模块修改日期，格式：YYYY-MM-DD>
	///</summary>

3.2类属性注释规范

在类的属性必须以以下格式编写属性注释：

/// <summary>
	///属性说明
/// </summary>

3.3方法注释规范

在类的方法声明前必须以以下格式编写注释

/// <summary>
	/// 说明：<对该方法的说明>
	/// </summary>
	/// <param name="<参数名称>"><参数说明></param>
/// <returns>
///<对方法返回值的说明，该说明必须明确说明返回的值代表什么含义>
/// </returns>

3.4代码间注释规范

代码间注释分为单行注释和多行注释：
单行注释：

//<单行注释>

多行注释：

/*多行注释1
多行注释2
多行注释3*/

代码行数太多而不容易区分时注释：

	/******************************************
	 *	代码块功能名称
	 ******************************************/
//<单行注释>
	或
/*多行注释1
	多行注释2*/

或者也可以使用下面方法：

/********* 代码块功能名称开始 ************/
//<单行注释>
//<单行注释>
/********* 代码块功能名称结束 ************/

注释说明
A. 代码中遇到语句块时必须添加注释（if,for,foreach,……）,添加的注释必须能够说明此语句块的作用和实现手段（所用算法等等）。 对一个数值变量采用不是0,-1等的数值初始化，给出选择该值的理由。
B. 尽量多点注释，就算能一目了然的命名最好也顺便写一写注释，方便以后接收的人能更容易理解程序（方便不太懂英文的程序员）。
C. 如果因为某种原因使用了复杂艰涩的原理，为程序配备良好的文档和更多的注释。

4.编码规范

1）缩进和间隔：缩进用TAB，不用 SPACES。

2）注释需和代码对齐。多使用#regedit和#endregion代码块。

3）在代码中垂直对齐左括号和右括号。

if (x == 0)
{
	Response.Write("用户编号必须输入！");
}
    不允许以下情况：
if(x == 0) {
	Response.Write("用户编号必须输入！");
}

或者：

if(x == 0){ Response.Write("用户编号必须输入！"); }

4）适当的增加空行，来增加代码的可读性。
在下列情况下应该有两行空行：
 同一文件的不同部分之间；
 在类，接口以及彼此之间；
在下列情况之间应该有一行空行：
 方法之间；
 局部变量和它后边的语句之间；
 方法内的功能逻辑部分之间；

5）避免使用大文件。如果一个文件里的代码超过300～400行，必须考虑将代码分开到不同类中。当然模板生成类与逻辑层类除外。

6）避免写太长的方法。一个典型的方法代码在1～25行之间。如果一个方法发代码超过25行，应该考虑将其分解为不同的方法。

7）为了防止在阅读代码时不得不滚动源代码编辑器，每行代码或注释在1024*768的显示频率下不得超过一显示屏

8）在大多数运算符之前和之后使用空格，这样做时不会改变代码的意图却可以使代码容易阅读。
例：

int j = i + k;  
而不应写为
int j=i+k;
括号和它里面的字符之间不应该出现空格。括号应该和它前边的关键词留有空格。
例：
while (true) 
{

};

但是方法名和左括号之间不应该有空格。
参数之间的逗号后应该加一空格。
例：

method1(int i1, int i2)

for语句里的表达式之间加一空格。
例：

for(expr1; expr2; expr3)

强制类型转换时，在类型和变量之间加一空格。
例：

(int) i ; 

9）所有可供用户输入的字段值，必须需忽略前后空白后(不包含密码)；在对字段值进行有效性验证。对提交进数据库的内容必须进行SQL注入过滤与XSS过滤。

10）一个方法只完成一个任务。不要把多个任务组合到一个方法中，即使那些任务非常小。

11）避免使用很多成员变量，声明局部变量，并传递给方法。

12）不要在方法间共享成员变量，如果在几个方法间共享一个成员变量，那就很难知道是哪个方法在什么时候修改了它的值。

13）不在代码中使用具体的路径和驱动器名，使用相对路径，并使路径可编程。永远别设想你的代码是在“C:”盘运行。你不会知道，一些用户在网络或“Z:”盘运行程序。

14）应用程序启动时作些“自检”并确保所需文件和附件在指定的位置。
如果需要的配置文件找不到，应用程序需能自己创建使用默认值的一份。如果在配置文件中发现错误值，应用程序要抛出错误，给出提示消息告诉用户正确值。

15）出现任何问题给用户一个友好的提示，错误消息需能帮助用户解决问题。
永远别用像“应用程序出错”，“发现一个错误”等错误消息。而应给出像“更新数据库失败，请确保登陆id和密码正确” 的具体消息。显示错误消息时，除了说哪里错了，还应提示用户如何解决问题。不要用像“更新数据库失败”这样的，要提示用户怎么做：“更新数据库失败，请确保登陆id和密码正确”

16）错误处理和异常事件
不要“捕捉了异常却什么也不做”。如果隐藏了一个异常，你将永远不知道异常到底发生了没有。
发生异常时，给出友好的消息给用户，但要精确记录错误的所有可能细节，包括发生的时间，和相关方法，类名等。

别写太大的 try-catch 模块。如果需要，为每个执行的任务编写单独的 try-catch 模块。 这将帮你找出哪一段代码产生异常，并给用户发出特定的错误消息
如果应用程序需要，可以编写自己的异常类。自定义异常不应从基类SystemException派生，而要继承于. IApplicationException。文章来源地址https://www.toymoban.com/news/detail-447615.html

到了这里，关于【软件工程】软件设计中的通用编码规范的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！