DotNet项目组编码规范

.net 的7层结构: 业务实体层,数据工厂层,数据工具层,数据接口层,数据实现层,业务逻辑层,界面层

 

 

一． 程序代码的注释

1．        存储过程的头部注释

每一个存储过程都要写注释，写在最前面。如

/*
Author：              Bill
Create Time：         2003-06-16 17:04
Last Modify Time：     2003-06-16 17:13
Version：                     1.0.01
Action describe：   
Memo：                      
*/

2．        存储过程的代码内部注释

存储过程的内部需要视情况添加注释，简单说明其功能、设计思想、算法等等。如：

/* SET NOCOUNT ON */

3．        CS文件的头部注释

每一个.CS文件都要写注释，写在CS文件的最前面。如

/*
File Name（文件名）：                    ClientServiceS.cs
Storage Path（存储路径）：                Capitalnet_MIS/EntityDAO/
Author（作者）：                         Bill
Create Time（建立日期及时间）：                     2003-06-16 17:04
Last Modify Time（最后修改日期及时间）：  2003-06-16 17:13
File Version（本文件版本号）：X.X.XXX     1.0.01
File Action describe（文件功能描述）：       客户服务实体访问层
File Memo（备注）：
*/

4．        类的注释

为你定义的类写详细的注释，包括作者、时间、版本修订信息、基本的算法，如：

/// <summary>
/// 类的简单描述
/// </summary>

5．        类成员的注释

每一个类的成员，如变量、属性等都要加相应的注释。

6．        方法的注释

为你定义的每一个函数写详细的注释，包括输入输出参数说明、返回值说明、函数功能说明：

/// <summary>
/// 取得本帐期的帐单
/// </summary>
/// <param name="contractGuid">合同Guid</param>
/// <param name="date">本帐期日期</param>
/// <returns>帐单列表</returns>

public static ContractPaidListData CalculateThisPaid(string contractGuid,DateTime date)
{ }

7．        代码内部的注释

关键代码必须加注释，简单说明其功能、设计思想、算法等等。长条注释（划分功能模块）、短条注释（说明实现的各步骤）与句后解释（说明重要句的意义）相结合，清晰功能的实现层次。如：

// Draw the string as normal and let then transforms do the work
/*
This is a test
*/

1)        一般来讲，按需要来注释，简明扼要。

2)        修改代码的注释，当有第二人开始修改代码时，应在每一次修改的代码部分加以注释，必须包括修改人，修改时间，还可以包括修改目的等。

8．        其他要点

1)        对上述较长者在范围结束处加注释。如//for 循环结束 。

2)        注释必须简明扼要，规范易懂。

二． 对象的可访问性设计

1)        不要随意定义类的public，这在基于组件的开发中相当重要。

2)        只有被其他类引用的函数才定义成public型函数。

3)        类中最好不用public型成员变量（一般使用属性来代替）。

4)        最好不使用全局变量。可以使用一些代替的方法。

三． 对象的命名规范

1．        命名要求

1)        所有命名（类、函数、变量..）均要求意义明确易于理解。

2)        避免在代码中直接使用数字等不确定意义的词，尽量使用有意义的串值代替。

例子：Protected Const string CAPTION_TITLE= "Bind Data to a ComboBox"

3)        在名字上区分各种变量及函数。

2．        命名约定

1)        常量命名规则。一般用大写具有意义的复合单词来定义。

                   protected Const string CAPTION_TITLE= "Bind Data to a ComboBox"

2)        字段（变量），开头将一小写字母开头，后面的具有意义的英语单词开始于大写。

               public string strName等

3)        属性，一般用大写字母开头，要具有一定的意义。

              Name;

4)        类名， 以大写字母开头的有意义的复合英语单词。对类名的定义还要考虑到该类的意义。

                   比如我们在项目中分了商务规则层、数据层、商务界面层、数据访问层等。我在下面给出一个Agent表在各层中进行处理的时候相关的类的命名：
         AgentData--àAgentS--àAgentR--àAgentF
                    (分别是：数据实体、数据访问层、商务规则层、商务界面层的命名)

5)        控件的命名规则，控件的命名可以以控件的缩写开头（小写），配以一定意义的英文单词；尽量让缩写可以理解。遇到新的控件可以大家讨论来制定。

                比如：
                Button： btnUpate
                 DropDownList: ddlstCity
                 Label: lblName
                 DataGrid : grdAgent
                 DataList : dlstAgent
                TextBox : txtName

           (等等)       

6)        文件名字的命名，以大写字母开头。DataAccess.cs

 

四． 数据表的定义和功能描述

1)        基础表的定义

基础表是指与业务无直接关系，仅为业务实现提供基础数据的数据库表。这类表有国家（Country）、货币（Currency）、单位（Company）、联系人(Contact)、产品（Product）、银行（Bank）等等。

2)        基础表提供的维护功能

对这些基础表要提供添加、修改、删除、查看等等维护功能。在这些功能中，查看功能是很重要的，要给出多个条件的查看功能的方法，以便别的功能模块的查看和引用的需要。

3)        业务表的定义

业务表则是指与业务直接相关，用以保存各项业务数据、实现各项业务功能的数据库表，这类表有合同（Contract）、项目（Project）、机会（Opportunity）、合同费用（ContractPaidList）等等。

4)        业务表提供的维护功能

对这些业务表要提供添加、修改、删除、查看等等维护功能。因为这些数据与业务息息相关，故要能给出多种查询的方法。这些业务会涉及到大量的业务逻辑，故需使用业务逻辑层对业务表中的数据进行处理。
 

五． 项目的分层定义和编码规范

1．        数据实体层的定义和编码规范

这一层主要定义类型化数据集的XML架构(XSD)。是数据库的内存表示，建立架构后代码由系统自动生成。

1)        添加数据集：添加à添加新项à数据集；

2)        定义数据表架构：

(1)    单表形式：从“服务器资源管理器”中将单表拖至设计界面，系统将自动生成表结构；

(2)    多表形式：

方法一.照上述方法生成多个表，然后手工添加表间关联（如果有的话）;

      方法二.照上述方法生成基本表，然后手工添加其他相关字段，组成一张表；

而他的XML格式这是这样的：

<?xmlversion="1.0"encoding="utf-8"?>

<xs:schemaid="AddressData"targetNamespace="http://tempuri.org/AddressData.xsd"elementFormDefault="qualified"

     attributeFormDefault="qualified"xmlns="http://tempuri.org/AddressData.xsd"xmlns:mstns="http://tempuri.org/AddressData.xsd"

     xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">

     <xs:elementname="AddressData"msdata:IsDataSet="true">

         <xs:complexType>

              <xs:choicemaxOccurs="unbounded">

                   <xs:elementname="City">

                       <xs:complexType>

                            <xs:sequence>

                                 <xs:elementname="CityID"msdata:ReadOnly="true"msdata:AutoIncrement="true"type="xs:int"/>

                                 <xs:elementname="Abbr"type="xs:string"/>

                                 <xs:elementname="NameGuid"msdata:DataType="System.Guid, mscorlib, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"

                                     type="xs:string"minOccurs="0"/>

                                 <xs:elementname="ProvinceID"type="xs:int"/>

                                 <xs:elementname="Remark"type="xs:string"minOccurs="0"/>

                                 <xs:elementname="Name"type="xs:string"minOccurs="0"/>

                            </xs:sequence>

                       </xs:complexType>

                   </xs:element>
        ……

2．          SQL层的定义和编码规范

这一层定义用于与数据库交互的SQL语句。

这一层负责生成用于操作数据库的SQL语句。根据要操作的数据实体层来分别的定义这一层要实现的方法，在本项目组中，我们一般只需要定义选择查询所需要的SQL语句。

这里的方法中所做的工作全部是拼装出一个用于实现所需求的功能的SQL语句。如：

public static string strGetLogonLog = "SELECT LogonLog.* FROM LogonLog";
     public static string GetLogonLogByUserName(string userName)
     {
        return strGetLogonLog + " WHERE (UserName = N'" +userName+ "')";
    }

3．          数据访问层的定义和编码规范

这一层负责操作数据库。

这一层负责对数据库进行各种操作。根据要操作的数据实体层来分别的定义这一层要实现的方法，在本系统中，一般要包括读取数据的方法和将数据更新回数据库的方法。

在这一层向上，数据将可能有两个流向：如果本模块有商务规则，数据将流向商务规则层；如果本模块没有商务规则，则数据将流向商务界面层。

编码示例如下：

public MenuData GetMenu()
    {  
        MenuData ds = new MenuData();
         DatabaseExecute dbExec = new DatabaseExecute();
         dbExec.GetData(ds.Menu,MenuSQL.strGetMenu);
         return ds;
    }

public void UpdateMenu(MenuData ds)
     {
         DataTableExtend dt = new DataTableExtend(ds.Menu,"Menu");
         DatabaseExecute dbExec = new DatabaseExecute();
         dbExec.ModifyDataBase(dt);
    }

4．        商务规则层的定义和编码规范

商务规则层负责实现业务逻辑，根据不同的业务逻辑需求，会有不同的实现方式。

商务规则层的代码开发规范不再赘述，只提出以下几点要注意的地方：

1)        所有的商务规则都在这一层实现。

2)        对于计算字段要分清字段值得到的计算公式。

3)        接口要尽量清晰。

举例如下：

public static ContractPaidListData CalculateFirstPaid(string contractGuid)
     {
         ContractS contractS = new ContractS();
         ContractData.ContractRow contract = contractS.GetContractByGuid1(contractGuid).Contract[0];
         ContractChargeDetailData contractChargeDetailDS = new ContractChargeDetailData()
         ContractChargeDetailS contractChargeDetailS = new ContractChargeDetailS();
         contractChargeDetailDS = contractChargeDetailS.GetContractChargeDetailByContractGuidAndOneFee(contractGuid);
         foreach (ContractChargeDetailData.ContractChargeDetailRow contractCharge in contractChargeDetailDS.ContractChargeDetail)
             {
                 decimal price;
                 int amount = 1;
                 if (!contractCharge.IsRealPriceNull())
                 {
                     price = contractCharge.RealPrice * amount;
                 }
                 else 
                    if (!contractCharge.IsDiscountNull())
                     {
                         price = contractCharge.StandardPrice *contractCharge.Discount/100 * amount;
                    }
                    else
                     {
                         price = contractCharge.StandardPrice * amount;
                     }
                     ContractPaidListData contractPaidDS = new ContractPaidListData();
                ……

5．        商务界面层的定义和编码规范

这一层提供界面和中间层的接口。

在这一层向下，数据将可能有两个流向：如果本模块有商务规则，数据将流向商务规则层；如果本模块没有商务规则，则数据将流向商务界面层。

这一层负责为界面层提供数据接口。根据要提供的接口功能分别的定义这一层要实现的方法，一般包括，InsertXXX(数据集)、UpdateXXX(数据集)、DeleteXXX(数据集)、LoadXXX()(用于返回一个数据集)、LoadXXXByXX(字段1，字段2…)(用于根据某个字段或多个字段来返回一个数据集)。

这一层要做的工作很少，只是起一个定义接口和传递数据的工作。如果本模块有商务规则，则先实例化一个商务规则层中对应的类并调用其中相应的方法；如果本模块没有商务规则，则先实例化一个实体访问层种对应的类并调用其中相应的方法。

示例如下：
     public SqlDataAdapter GetCountry()
     {
         try
         {
             CountryS countryS = new CountryS();
             SqlDataAdapter m_Sql = countryS.GetCountry();
             return m_Sql;
         }
        catch(Exception e)  
        {
             throw e;
         }
    }

6．        界面层的定义和编码规范

界面层提供用户界面并处理用户操作。

这一层应尽量与后台分离，即，界面代码的作用应当主要是处理用户操作而不是业务逻辑的实现。其目的是为了将来方便的更换界面甚至更改平台，如从C/S转向B/S或者想反。

在这一成上得工作就是界面与数据实体的同步，如把数据显示到界面上或者把界面数据的更改同步回数据实体：

public void InitControl()
     {
         try
         {
             if (GetRequest() == null)
             {
                title.Text="新增： ";
                 this.SetTextNull();
                 btnDel.Visible = false;
            }
             else
             {
                title.Text="修改、删除： ";
                btnSubmit.Value="确定修改 ";
                 btnReset.Visible=false;
                 CityData cityDS = new CityData();
                 CityF.GetCitiesByGuid(GetRequest()).Fill(cityDS.Cities);
                 CityData.City city = cityDS.Cities[0];
                 txtCityName.Text = city.CityName;
               
    ……

private void btnSubmit_ServerClick(object sender, System.EventArgs e)
     {
         try
         {
             if(!Page.IsValid)
             {
                 this.ValidateMessage();
            }
             else
             {
                 if (GetRequest() == null)
                 {
                     CityData cityDS = new CityData();
                     CityData.City city = cityDS.Cities.NewCity();
                     city.Guid = GUIDGenerator.GetNewGUID();
                     city.CityName = txtCityName.Text.Trim();
                ……

六． 项目各层暴露的接口

1．        SQL层的接口

这一层暴露的接口主要是为数据访问层提供的各种操作SQL语句，如用于各种方式的查询、新增、修改、删除的SQL等等。

对于传入方法中的参数，Get方法传入一个或若干个需要用于查询的参数，为字符串值，Insert、Update和Delete方法不传入任何参数；而对于返回值，所有的方法全部返回一个字符串。

例如：

public static System.String DeleteCity (  )

public static System.String GetCities (  )

public static System.String GetCitiesByAbbr ( System.String cityName )

public static System.String InsertCity (  )

public static System.String UpdateCity (  )

但在本项目组中，一般只需要写Get方法。

2．        数据访问层的接口

这一层暴露的接口则是供上层调用以对数据库做各种操作。

对于Load方法，首先获取数据库连接并打开，然后利用SQL定义层中定义的方法和刚才的数据库连接实例化一个SqlDataAdapter并将其作为返回值返回。返回前将数据连接关闭；

对于Update方法，首先获取数据库连接并打开，然后对类型化数据集中的数据进行操作。操作中，先利用SQL定义层中定义的方法和刚才的数据库连接实例化一个SQLCommand，然后将对应数据值赋给参数并执行SQLCommand。操作完成后返回操作是否成功的布尔值。返回前将数据连接关闭。

例如：

public static System.Data.SqlClient.SqlDataAdapter GetCities (  )

public static System.Data.SqlClient.SqlDataAdapter GetCitiesByAbbr ( System.String cityName )

public static System.Boolean UpdateCities ( Capitalnet_MIS.Common.EntityDefinitions.CityData cityDS )

3．        商务规则层的接口

商务规则层的接口并没有一个统一的规范，根据实际需要而定。

例如：

public static Capitalnet_MIS.Common.EntityDefinitions.ContractPaidListData CalculateContractAmount ( System.DateTime date1 , System.DateTime date2 , System.Decimal total , System.Decimal paidTotal , System.Decimal unPaidTotal )

public static Capitalnet_MIS.Common.EntityDefinitions.ContractPaidListData CalculateFirstPaid ( System.String contractGuid )

4．        商务界面层的接口

这一层的接口很关键，因为这一层起一个连接界面层和中间层的作用。

对于传入方法中的参数，Get方法传入一个或若干个需要用于查询的参数，为字符串值， Update方法传入一个强类型的数据集；而对于返回值，Load方法返回一个类型化的数据集， Update方法返回一个布尔值。

例如：

public static System.Data.SqlClient.SqlDataAdapter GetCities (  )

public static System.Data.SqlClient.SqlDataAdapter GetCitiesByAbbr ( System.String cityName )

public static System.Boolean UpdateCities ( Capitalnet_MIS.Common.EntityDefinitions.CityData cityDS )

七． 界面逻辑

界面逻辑如下图所示：