Skip to content

Latest commit

 

History

History
339 lines (218 loc) · 15.8 KB

codestyle.md

File metadata and controls

339 lines (218 loc) · 15.8 KB
Raw

代码规范

[toc]

Csharp

基本代码格式

缩进

一定不要使用制表符。不同的编辑器使用不同的空格来生成制表符，这就带来了格式混乱。所有代码都应该使用4个空格来表示缩进。

配置Visual Studio 文字编辑器，以空格代替制表符 。

花括号

花括号一定独占一行。关于花括号的格式问题，也是很多人争论的点，有些人习惯于Java的左花括号跟在圆括号后面，但微软官方推荐的是花括号应该独占一行，不与任何语句并列一行。

左花括号 “{” 放于关键字或方法名的下一行并与之对齐。左花括号 “{” 要与相应的右花括号 “}”对齐。

错误的示范：

public static void Main(string[] args) {
            
}

正确的示范：

public static void Main(string[] args) 
{
            
}
if、while、do语句后一定要使用{}，即使{}号中为空或只有一条语句。如：

if (somevalue == 1)
{
    somevalue = 2;
}

右花括号 “}” 后建议加一个注释以便于方便的找到与之相应的 {。如:

while(1)
{
    if(valid)
   {
   } // if valid
   else
   {
   } // not valid
} // end forever

例外的，类的自动属性花括号与代码合占一行：

public string Name{get;set;}

using排序

引入的命名空间应该按照字母音序排列，这样做的目的在于方便在引入的多个命名空间中直接快速的找到命名空间。

换行

当表达式超出或即将超出显示器一行显示范围的时候，遵循以下规则进行换行：

  1. 在逗号后换行。
  2. 在操作符前换行。

规则1优先于规则2。

当以上规则会导致代码混乱的时候自己采取更灵活的换行规则。

空行

空行是为了将逻辑上相关联的代码分块，以便提高代码的可阅读性。

在以下情况下使用两个空行：

  1. 当接口和类定义在同一文件中时，接口和类的定义之间。
  2. 当枚举和类定义在同一文件中时，枚举和类的定义之间。
  3. 当多个类定义在同一文件中时，类与类的定义之间。

在以下情况下使用一个空行：

  1. 方法与方法、属性与属性之间。
  2. 方法中变量声明与语句之间。
  3. 方法与方法之间。
  4. 方法中不同的逻辑块之间。
  5. 方法中的返回语句与其他的语句之间。
  6. 属性与方法、属性与字段、方法与字段之间。
  7. 语句控制块之后，如if、for、while、switch。
  8. 注释与它注释的语句间不空行，但与其他的语句间空一行。

空格

在以下情况中要使用到空格：

  1. 关键字和左括符 “(” 应该用空格隔开。如：while (true)
  2. 注意在方法名和左括符 “(” 之间不要使用空格，这样有助于辨认代码中的方法调用与关键字。
  3. 多个参数用逗号隔开，每个逗号后都应加一个空格。

除了 . 之外，所有的二元操作符都应用空格与它们的操作数隔开。一元操作符、++及--与操作数间不需要空格。如：

a += c + d;
a = (a + b)/(c*d);
while (d++ == s++)
{
    n++;
}
PrintSize("size is " + size + "\n");

语句中的表达式之间用空格隔开。如：for (expr1; expr2; expr3)

文件定义

通常情况下，一个cs文件只能定义一个类、接口、枚举、结构体，特殊情况可将多个类定义在同一cs文件，如代码生成器生成的代码或紧密关联的两个class。

其次类名应该与cs文件名保持一致，以便于通过文件名查找类名，比如UserInfo类应该在UserInfo.cs文件里。

语句

一定不要在同一行内放置一句以上的代码语句。 这会使得调试器的单步调试变得更为困难。

错误示范：

a = 1; b = 2;

正确示范：

a = 1;

b = 2;

命名规范

基本命名规范

  1. 一定要为各种类型，函数，变量，特性和数据结构选取有意义的命名。其命名应该能直接反映其作用。所谓自注释的代码就是好代码。

  2. 名称应该说明“什么”而不是“如何”。通过避免使用公开基础实现（它们会发生改变）的名称，可以保留简化复杂性的抽象层。例如，可以使用GetNextStudent()，而不是 GetNextArrayElement()。

  3. 不应该在标识符名中使用不常见的或有歧义的缩短或缩略形式的词。比如，使用 “GetTemperature” 而不是 “GetTemp”，Temp到底是Temperature的缩写还是Temporary的缩写呢。对于公共类型或大家都知道的缩写，则可以使用缩略词，如：线程过程，窗口过程，和对话框过程函数，为“ThreadProc”,“DialogProc”, “WndProc” 等使用公共后缀。

  4. 一定不要使用下划线，连字号，或其他任何非字母数字的字符。

  5. 不要使用计算机领域中未被普遍接受的缩写。

  6. 在适当的时候，使用众所周知的缩写替换冗长的词组名称。例如，用 UI 作为 User Interface 缩写，用 OLAP 作为 On-line Analytical Processing 的缩写。

  7. 在使用缩写时，对于超过两个字符长度的缩写请使用 Pascal 命名法或驼峰命名法。例如使用 HtmlButton 或 HTMLButton；但是，应当大写仅有两个字符的缩写，如：http://System.IO，而不是http://System.Io。

  8. 不要在标识符或参数名称中使用缩写。如果必须使用缩写，对于由多于两个字符所组成的缩写请使用驼峰命名法。

命名原则

选择正确名称时的困难可能表明需要进一步分析或定义项的目的。使名称足够长以便有一定的意义，并且足够短以避免冗长。唯一名称在编程上仅用于将各项区分开。表现力强的名称是为了帮助人们阅读；因此，提供人们可以理解的名称是有意义的。不过，请确保选择的名称符合适用语言的规则和标准。

推荐的命名法

  1. Pascal命名法：将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用Pascal 命名法。例：BackColor

  2. 驼峰命名法：标识符的首字母小写，而每个后面连接的单词的首字母都大写。例：backColor

不推荐的命名法

  1. 匈牙利命名法：匈牙利命名法是一名匈牙利程序员发明的，这种命名法的基本原则是：变量名＝属性＋类型＋对象描述，如：m_bFlag：

    m表示成员变量，b表示布尔，合起来为：“某个类的成员变量，布尔型，是一个状态标志”。

一定不要在.NET中使用匈牙利命名法 （例如，不要在变量名称内带有其类型指示符）。

推荐的命名方法：

  1. 避免容易被主观解释的难懂的名称，如AnalyzeThis()，或者属性名Temp。这样的名称会导致多义性。

  2. 在类属性的名称中包含类名是多余的，如User.UserName。而是应该使用User.Name，“.”即中文的“的”的意思。

  3. 只要合适，在变量名的末尾或开头加计算限定符（Avg、Sum、Min、Max、Index）。

  4. 在变量名中使用互补对，如 min/max、begin/end 和 open/close。

  5. 布尔变量名通常应该包含Is，这意味着True/False值，如fileIsFound，若单词的意义本身已经包含是非的情况，可省略Is，如Exist。

  6. 在命名状态变量时，避免使用诸如Flag的术语。状态变量不同于布尔变量的地方是它可以具有两个以上的可能值。比如订单状态不应该是OrderFlag，而是使用更具描述性的名称，OrderStatus。

  7. 即使对于可能仅出现在几个代码行中的生存期很短的变量，仍然需要使用有意义的名称。仅对于短循环索引使用单字母变量名，如 i 或 j。

  8. 定义方法名通常使用动词，接口通常使用形容词，类名、属性名、字段名、参数名通常使用名词。

常用的命名规范

  1. 命名严禁使用拼音与英文混合的方式，更不允许直接使用中文。正确的英语拼写和语法可以让阅读者易于理解，避免歧义。注意：即使纯拼音命名的方式也要避免采用。 正例：name / order / baidu / alibaba 等国际通用的名称可视为英文。 反例：zhekou(折扣)/Shuliang(数量)/ int 变量=1

  2. 类名使用Pascal命名法，某些情况例外：DTO/UID等模块功能缩写或接口定义IInterface。 正例： UserDTO / XmlService / TFlowInfo /TTouchInfo /IUserService 反例： userDto / XMLService / tflowInfo / ttouchInfo

  3. 方法名、参数名、成员变量、局部变量都统一使用驼峰命名法，必须遵从驼峰形式。 正例： name / getUserInfo() / userId

  4. 常量的命名使用Pascal命名法，单词力求语义表达要完整，不要嫌名字长。 正例：MaxStockCount 反例：Max_Count

  5. 抽象类命名推荐使用Base结尾，异常类命名使用Exception结尾，测试类命名以它要测试的类的名称开始，以Test结尾。杜绝不规范的缩写，避免望文不知义。 反例：NotFoundException 缩写命名为 NotFoundEx

  6. 为了达到代码自注释的目标，任何自定义编程元素在命名时，尽量使用完整的单词组合来表达其意思。 反例：int a的随意命名方式

  7. 如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。 正例：public class OrderFactory / public class LoginProxy

  8. 接口和实现类的命名须遵循以下两点规则： （1）对于Service和DAO类，暴露出来的服务一定是接口。正例：CacheService实现自ICacheService接口。 （2）如果形容能力的接口名称，取对应的形容词为接口名（一般为-able结尾），正例：IDisposeable接口。

  9. 枚举类的成员名称使用Pascal命名法，枚举为特殊的类，成员均为常量，并为其显式指定枚举值，防止将来在中间插入枚举变量导致枚举值混乱，同时最好为没个枚举值打上Description标签。

正例：

public enum PaymentStatus : sbyte
    {
        /// <summary>
        /// 进行中
        /// </summary>
        [Description("进行中")]
        Processing = 1,
        /// <summary>
        /// 成功
        /// </summary>
        [Description("成功")]
        Succeed = 2
    }

各层命名规约：

A) Service/DAO 层方法命名规约 1）获取单个对象的方法用 Get 做前缀。 2）获取多个对象的方法用List做后缀，如：GetOrdersList。 3）获取统计值的方法用 Count 做后缀。 4）添加或更新的方法用 Save或Add。 5）删除的方法用 Remove/Delete。 6）修改的方法用 Update。 B) 领域模型命名规约 1） 实体对象：如UserInfo，UserInfo即为数据库表名。 2） 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。 3） 展示对象：xxxViewModel，xxx 一般为网页名称。

命名空间和程序集命名

命名空间名称采用Pascal命名法，且首字符大写。命名空间名称尽量反映其内容所提供的整体功能，一般以“域名.项目名.模块名”的命名方式。如：Masuit.MyBlogs.Models。

其次命名空间应该与文件夹层级结构保持一致，比如在项目Masuit.MyBlogs.Core中，Masuit.MyBlogs.Core.Infrastructure.Services则表示该命名空间位于项目的Masuit.MyBlogs.Core/Infrastructure/Services文件夹下。

Java

代码规范

  • 缩进
    • 缩进采用4个空格
  • 运算符
    • 任何运算符左右必须加一个空格
  • 命名
    • 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式。
    • 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
    • 不允许出现任何魔法值（即未经定义的常量）直接出现在代码中。
  • 换行规则
    • 单行字符数限制不超过 120个，超出需要换行
  • 构造方法
    • 当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，便于阅读。
  • 注释
    • 能够准确反应设计思想和代码逻辑；
    • 能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。

更多细节查看此处输入链接的描述

[HTML][2]

第一部分：HTML整体结构

1.HTML基础设施

文件应以<!DOCTYPE.....>首行顶格开始，这句话告诉浏览器这是一个什么文件，我们推荐使用<!DOCTYPE html>。

必须在head元素内部的meta标签内声明文档的字符编码charset, 如：<metacharset="UTF-8">，这句代码告诉浏览器应该此HTML文件使用的字符集是什么，如果不加此行代码，那么在浏览器中可能显示为乱码。

页面的title是极为重要的不可缺少的一项。

2.HTML代码结构和视觉顺序基本保持一致

按照从上之下，从左到右的视觉顺序书写HTML结构。

有时候为了便于搜索引擎抓取，我们也会将重要内容在HTML结构顺序上提前，以为搜索引擎抓取网页内容是自上而下的，所以将重要内容在HTML结构顺序上提前可便于抓取重要的内容。

不要使用table布局，现在基本上被淘汰了，而应该代之以div来布局，方便控制。

3.结构、表现、行为三者分类，避免内联。

使用link引入外部css文件到head中。注意：一般我们不适用@import来引入外部css文件。 使用script将js文件引入，并置于body底部，这时js文件会最后加载，html会最先加载，用户体验会更好。(注意：并不是所有的js文件都要放置于body的底部，如当我们需要使用js文件动态修改meta元素内容时，需要将js文件引入到head标签中。

4.保持良好的树形结构

每一个块级元素都另起一行，每一行都是用tab缩进对齐。如果不是块级元素，比如几个行内元素，我们把他写在一行即可。注意：html、 head、 body 以及body下的第1级标签(即直接子元素)不缩进，其他的都正常缩进。如下图所示：

当然，我们也可以在大的模块之间用空行空开，在模块内不要使用多余的空行。

5.其他需要注意的问题

一个标签上引用的className不要过多，越少越好。 对于一个语义化的内部标签，应该尽量避免使用className。

第二部分：HTML代码格式

1.说明文案的注释方法

  • 开始注释：<!-- 注释文案 -->
  • 结束注释：<!-- /注释文案 -->
  • 允许只有开始注释。

2.严格嵌套

应当以最严格的xhtml strict标准来嵌套，不如内联元素不能包含块级元素等等。 正确闭合标签且必须闭合。

3.严格的属性

属性和值全部小写，每个属性都必须有一个值，每个值必须加双引号。 没有值的属性必须使用自己的名称做为值(checked、disabled、readonly、selected等等)。 可以省略style标签和script标签的type属性。

##第三部分：HTML内容语义

  • 加强资源型内容的可访问性和可用性。

比如在img标签内加入alt属性，在audio内加入文案和链接等等。

  • 加强不可见内容的可访问性

比如背景图片的文字应该同时卸载HTML中，并使用css使其不可见，有利于搜索引擎抓取你的内容，也可在css失效的情况下看到内容。

  • 适当使用实体

以实体代替与HTML语法相同的字符，避免浏览器解析错误。