这套C#编码规范写不错

时间:2022-04-08 08:16:32

自己总结的C#编码规范--1.命名约定篇:http://www.cnblogs.com/luzhihua55/p/CodingConventions1.html

自己总结的C#编码规范--2.命名选择篇:http://www.cnblogs.com/luzhihua55/p/3868258.html

自己总结的C#编码规范--3.特定场景下的命名最佳实践:http://www.cnblogs.com/luzhihua55/p/3873015.html

命名约定

我们在命名标识符时(包括参数,常量,变量),应使用单词的首字母大小写来区分一个标识符中的多个单词,如UserName.

  • PascalCasing

PascalCasing包含一到多个单词,每一个单词第一个字母大写,其余字母均小写。例如:HelloWorld、SetName等。

除了参数、变量、常量外,所有命名空间名称、类、函数、接口、属性、事件、枚举等名称的命名,使用 Pascal 风格。

  • camelCasing

camelCasing包含一到多个单词,第一个单词首字母小写,其余单词首字母大写。例如:name、productId等。

参数与变量的命名使用camelCasing.

  • SCREAMING_CAPS

SCREAMING_CAPS包含一到多个单词,每个单词的所有字母都大写,单词与单词之间用"_"连接,该风格目前在c#中只用于const常量。

如:public const string DEFAULT_PAGE = "default.aspx";

  • 私有变量的命名

Private 的私有变量使用下划线"_"+camelCasing的大小写规则,以便快速确认该变量的作用域。

如: private int _userId;

  • 首字母缩写词的大小写

首字母缩写词是由一个短语的首字母组成的,如Xml(ExtensibleMarkuLaguage),IO(Input and Output)。它和单词缩写是有区别的,单词缩写仅仅是把一个单词的长度变短。

  1. 把两个字母的首字母缩写词全部大写,除非它是camelCasing的第一个单词。

    using System.IO;

    public void StartIO(Stream ioStream)

  2. 由三个或以上的字母组成的首字母缩写词,只有第一个字母大写,如Xml,Html.除非首字母是camelCasing标识符的第一个单词。

    using System.Xml;

    public void ProcessXmlNode(XmlNode xmlNode)

  • 复合词的大小写

不要把复合词中的首字母大写。复合词要当成一个单词来处理。

如endpoint, callback,metadata,namespace等都是正确的写法

  • 在带单位的值的变量后加上"_camelCasing单位"

将单位加入标识符命名中,可以使使用者快速准确的知道传人数据的单位,减少错误的发生。

如public void CreateCache(int cacheSize)

传入的数据是bytes, KB, MB 还是GB?

改成public void CreateCache(int cacheSize_mb)

一目了然,并且会减少调用者传入错误数据的可能。

其他一些没有单位的函数参数以及带单位的版本。

这套C#编码规范写不错

  • 不要使用匈牙利命名法

匈牙利命名法是指用小写形式的数据类型缩写来作为变量名的前缀。如:strName,intCount。

这种命名法在C和C++时代很流行,可以帮助程序员记住自己的类型。

但在C#中需要禁用,除非你有足够的理由,因为:

  1. C#都是强类型的,现在的IDE(如Visual Studio)可以自动的检测出当前变量的类型以及类型错误

    这套C#编码规范写不错

  2. 开发初期经常需要修改变量的类型,使用匈牙利命名法维护很困难。
  • 使用英语语序命名标识符

人在阅读代码时,能更快的理解符合其阅读习惯的命名。

如VerticalAlignment比AlignmentVertical能让人更快的知道该变量的含意。

简单的讲,看到一个标识符一定要可以见名知意。

  • 名字一定要能够表达出标识符的含意

标识符名字必须要表达出该标识符的意义,绝对不可以使用无意义的v1,v2…vn之类的命名。

public static void CloneChars(char[] cl1, char[] cl2)

{

for (var i = 0; i < cl1.Count(); i++)

{

cl2[i] = cl1[i];

}

}

代码的调用者不看这函数是无法知道cl1还是cl2是要拷贝的char数组,他必须进到这个函数去看完整个逻辑才可以调用。而且在看的过程中cl2[i] = cl1[i]; 也需要他花几秒钟来思考是做什么的。

如果改成有意义的名字: source 和target那么这个方法调用者一看名字就知道使用方法了。

public static void CloneChars(char[] source, char[] target)

{

for (var i = 0; i < source.Count(); i++)

{

target[i] = source[i];

}

}

  • 选择意义单一明确的名字

在命名时要使用专业的单词,避免使用"空洞"的单词

如: class BinaryTree

{

public int Size()

看到这行代码你想到Size会返回什么,树的高度,节点数还是树在内存中的空间?

我们可以使用更单一明确的词来告诉读者这个方法的具体含义,如Height,NodesNum,Memory_Bytes

  • 使用不会产生歧义的名字

这套C#编码规范写不错

在给标识符命名时,一定不能产生歧义,代码中的很多错误都是由于命名时的歧义造成的。例如:

public const int CART_TOO_BIG_LIMIT = 10;

if (ShoppingCart.Count() >= CART_TOO_BIG_LIMIT)

{

LogError("Too many items in cart.");

}

这段代码有个很经典的"大小差一缺陷"。在判断购物车物品上限时,我是应该使用 ">"还是应该使用">=",我是无法从代码中判断出来的,所以这个地方很容易出现bug.如果我们换成MAX_ITEMS_IN_CART, 那我马上就可以判定出这里要使用">"。

  • 命名要与使用者的期望相匹配

有些名字之所以会让人误解是因为带吗阅读者对它们有先入为主的印象,就算你本意并非如此。这种情况下,你最好是选用一个与使用者期望所匹配的名字。

如很多程序员都习惯了把Get开始的方法当作"轻量级访问器",他只是简单的返回成员变量。

大家看到以下的代码

class BinaryTree

{

public int GetNodesCount()

会以为只是返回内部private int _nodesCount; 私有变量的访问器。

但如果实际你的代码可能是一个非常耗时的代码,内部实现是广度优先遍历所有的树节点,还要去数据库查找父节点和子节点的关系,然后累加。

那么这么一个耗时的方法可能由于你的命名,导致了被调用者反复多次的调用,导致整个系统性能下降。

如果你将命名改为ComputeNodesCount那么调用者就会知道这是个耗时的操作,需要缓存调用结果并减少调用。

  • 为名字附加更多的信息

这套C#编码规范写不错

一个变量名就像一个小注释,尽管空间不大,但不管你在命中挤进任何额外的信息,每次有人看到命名时都会看到这些信息。

例子:当你从网页接收了请求的表单,里面可能还有不安全的代码,如注入语句等,这时你在命名时需要体现该数据不安全,可以使用unsafeFormData,当调用完安全检查方法后可以将其改为 safeFormData = HandleUnsafeData(unsafeFormData).这样代码阅读者就知道可以放心的使用该变量了。

下表给出了更多需要给名字附加额外信息的例子

这套C#编码规范写不错

  • 不要卖弄风骚

使用最常用,众所周知的单词。不要在代码命名时卖弄你的学识,要让你的代码快速准确的表达出你的想法才是真正的牛人。

如public static string ConvertXml2Html (string sourcePath)

有些人在看到这个方法的时候怎么想也想不明白这个2是做什么用的,是把一个Xml文件变成两个Html?

熟悉英语文化的人可能知道这是To的俚语表达。如果你不能保证所有阅读你代码的人都知道2是To的缩写。那么请使用ConvertXmlToHtml命名。

特定场景下的命名最佳实践

  • 命名空间

  1. 要使用PascalCasing,并用点号来分隔名字空间中的各个部分。

    如Microsof.Office.PowerPoint

  2. 要用公司名作为命名空间的前缀,这样就可以避免与另外一家公司使用相同的名字。
  3. 要用稳定的,与版本无关的产品名称作为命名空间的第二层
  4. 不要使用公司的组织架构来决定命名空间的层次结构,因为内部组织结构经常改变。
  5. 不要用相同的名字来命名命名空间和该空间内的类型。

    例如,不要先将命名空间命名为Debug,然后又在该空间中提供Debug类。大部分编译器包括VS要求用户在这样的类型前加上完整的限定符。

  • 要让接口的名字以字母I开头

如IComponet,IDisposable 大家一看就知道是接口。

同时要确保如果一个类是一个接口的标准实现,那么这个类和接口应该只差一个"I"前缀。

  • 派生类的末尾使用基类名称

例如,从 Stream 继承的 Framework 类型以 Stream 结尾,从 Exception 继承的类型以 Exception 结尾。

  • 泛型类型参数的命名

  1. 使用描述性的名字来命名泛型类型参数,并且在前面加上T前缀

    如下面都是很好的命名

    public delegate TOutput Converter<TInput, TOutput>(TInput from);

  2. 如果只有一个类型参数,可以只用一个字母T来表示泛型

    public class Nullable<T>

    public class List<T>

  3. 如果泛型参数有约束,那么需要在泛型类型参数名中需要显示出该约束

    public interface ISessionChannel<TSession> where TSession:ISession

  • 枚举类型的命名

  1. 要用单数名词而不是复数命名枚举类型,如要用ConsoleColor而不是ConsoleColors

    public enum ConsoleColor

    {

    Red,

    Yellow,

    Blue

    }

  2. 不要给枚举类型加"Enum"、"Flag"等后缀。

    ColorEnum,ColorFlag都不好,因为本身就是枚举,再加上就是没有意义的重复 。

  • 要用动词和动词短语命名方法

  • 属性的命名

  1. 要用名词、名词短语或形容词来命名属性
  2. 要用描述集合中具体内容的短语的复数形式来命名属性集合,而不要用短语的单数形式加"List"、"Array"或"Collection"后缀

    class BinaryTree

    {

    //Good Naming

    public NodeCollection Nodes { get; set; }

    //Bad Naming

    public NodeCollection NodesCollection { get; set; }

  3. 要用肯定性的短语命名布尔属性。最好在前面选择性的加入"Is"、"Can"、"Has"等前缀。

    CanSeek比CantSeek和Seekable都更准确和容易理解。

  • 事件的命名

  1. 要用动词或动词短语命名事件

    如: Clicked、Painting、DroppedDown 等等

  2. 要用现在进行时(ing)和过去式(ed)来赋予事件发生之前和之后的概念。而不是使用Before和After.

    如窗口关闭前发生的close事件应该命名为Closing,而在窗口关闭之后发生的应该命名为Closed.

  • 字段的命名

    1. 禁止使用实例的公有字段和受保护字段,请使用属性代替。

    Tips:在VisualStudio中输入"prop"可快速创建外部可修改的属性,输入"propg"可快速创建不允许外部修改的属性。如:

//propg

public int NodesCount { get; private set; }

//prop

public List<BinaryNode> Nodes { get; set; }

  1. 一般只使用静态字段
  2. 要使用名词、名词短语或形容词命名字段
  3. 不要给字段加前缀如"g_"、"s_"来表示静态字段。因为字段和属性是非常相似的,所以要遵循相同的命名规范。