你用过这种奇葩的C#注释吗？如何看待 - 文章 - 伯乐在线
& 你用过这种奇葩的C#注释吗？如何看待
本人虽然不是专业开发人员，也非专业出身，但一直使用C#堆码，解决自己日常的小问题。包括自己的研究，也是用C#来实现和测试。对C#是情有独钟。虽然C#的很多高级技术不会用，也不太懂，但总归是知道，耳闻目染，都多多少少了解一点。因为研究开源组件和技术比较多的原因，经常翻别人的代码（大部分是国外的），免不了要翻译，所以我也是经常翻译和总结，例如我前2个翻译的一些机器学习的文章：
其实翻译一直在进行，也完成很多了，但还没有时间整理和发表上来给大家分享。但是前不久在看代码（也是翻译的一部分）过程中，发现了一个非常奇葩的注释，所以顺手就搜索引擎翻了翻，总结一下，同时大家也谈谈如何看待这种写法。
由于对代码的注释很多人都有不同见解，包括前段时间，博客园新闻里面有篇文章，大概意思是说有注释，说明本身代码就很烂，所以用注释来补充。当然我并不认同这种观点，虽然也有一点点道理。
声明：有可能本人见识比较少，可能很多人见过，也用过，我第一次见到，反正有点震惊，当然肯定是符合语法要求的，所以写出来，请轻拍。
1.C#的注释方式
搞C#的人应该都清楚，C#有3种标识注释的方式：
1.1 三斜杠(///)方式
一般用于类或者方法的前面，如下面的代码：
/// &summary&
/// 这里是注释。。。。。
/// Latent Dirichlet Allocation (LDA) model implemented in Infer.NET.
/// This version scales with number of documents.
/// &/summary&
/// &summary&/// 这里是注释。。。。。/// Latent Dirichlet Allocation (LDA) model implemented in Infer.NET./// This version scales with number of documents./// &/summary&
1.2 双斜杠(//)方式
一般是对临时变量，属性等的注释，当然也可以用在类或者方法前面，反正都是注释，如下面的代码：
1 //---------------------------------------------
2 // The model
4 Range D = new Range(NumDocuments).Named("D");
1 //---------------------------------------------2 // The model4 Range D = new Range(NumDocuments).Named("D");
1.3 块注释(/*XXXX*/)方式
一般用于一段连续的注释代码块，如下面的代码：
/* 这段程序已经不再有用
* 因为我们发现千年虫问题只是一场虚惊
* 我们的系统不会恢复到1/1/1900
/* 这段程序已经不再有用* 因为我们发现千年虫问题只是一场虚惊* 我们的系统不会恢复到1/1/1900 */
我印象中，C#的注释的标识符应该就是这3种把，当然其他的一些注释类型参数，我们不讨论。
2.这样注释奇葩么？
上面三种注释方式大家肯定都用过，估计也是和我一样(大部分)，写在类，属性或者临时变量前面，另起一行。
我这里说的奇葩，并不是脱离三种方式，而是其注释的位置，但是在浏览一段开源的代码的时候，发现了这个注释，当时吃惊，然后是思考，先看看：
上面一段代码包括了前面提到的3种注释方式，红色框里面的就是我说的 奇葩注释，用的是 /* */块方式，写在数组定义的中间，毫无疑问，这肯定是可以运行的。只是以前没想到可以这样，可能局限于自己的思维方式。
根据我的理解，开发人员这样注释的目的，由于这段代码的变量包含的信息量很大，这样写更加直接明了。但是否多余，也可以直接在变量上面进行说明？
反过来想一想，在一些很复杂的问题中，变量的初始化可能非常复杂，这里的数组长度是2，如果是20，那怎么办？这样写优势就出来了，可以使得看代码的人，一目了然。
又在一个地方发现了一段类似注释的代码，是这样的：
3.对自己好用，那就用起来
刚开始有点接受不了，为了这个事情，我回忆了自己很多写过的代码，还特意翻了翻，最终我觉得以后在自己的代码中也可以逐步在合适的地方采用这种方式，一方面是由于以前没想到可以这样用，思维局限在哪里，习惯另起一行说明；另一方面的确是有很多代码需要这样明了的注释，可能自己的代码和架构能力不够，在很多地方耦合很严重，不得不通过很多的注释来表现自己的想法，而变量有特别多，像这种初始化的情况，的确是很很说明，看看我修改后的一段代码例子：
3.1 以前注释方式
以前的一段代码中，有一个固定的有限列表，是公司编号，但实际开发的时候，经常要知道对应的名称，当然数据库里面可以去查找，但代码里面直接看不到，所以我这样写的：
//权威公司编号名称(顺序)："澳门","金宝博","立博","威廉希尔","伟德","10BET","bet 365","SNAI"
static List&Int32& AuthCompanyIdList = new List&int&(){ 247, 250, 251, 252, 253, 1, 469, 179};
//权威公司编号名称(顺序)："澳门","金宝博","立博","威廉希尔","伟德","10BET","bet 365","SNAI"static List&Int32& AuthCompanyIdList = new List&int&(){ 247, 250, 251, 252, 253, 1, 469, 179};
所以以前每次打开的时候，有错误或者手动排查一些信息，对着编号去注释找，虽然次数很少，但偶尔也要用到。所以看到上面的注释方式后，修改了一下。
3.2 现在的注释方式
修改后的代码是这样的，不是特意去改，是这样改之后，我自己也觉得好多了，看到这个代码就知道意思了。
internal static List&Int32& AuthCompanyIdList = new List&int&(){
247/*澳门*/, 250/*金宝博*/,
251/*立博*/, 252/*威廉希尔*/, 253/*伟德*/, 1/*10BET*/,
469/*bet 365*/, 179 /*SNAI*/
　　　　　　　　};
internal static List&Int32& AuthCompanyIdList = new List&int&(){&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&247/*澳门*/, 250/*金宝博*/, &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&251/*立博*/, 252/*威廉希尔*/, 253/*伟德*/, 1/*10BET*/, &&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&469/*bet 365*/, 179 /*SNAI*/&&&&&&&&&&&&&&&& 　　　　　　　　};
其实哪种都可以，重要的是你看得懂，方便看，所以如果你觉得有用，可以用上，觉得纯属无聊，那就跳过吐槽一下。
4.最后猜猜谁写的
敲代码应该是件轻松的事情，如果能把代码写得非常优雅，好懂，当然最好不过了。最后娱乐一下，猜猜这代码来自哪里？
A：某商业机器学习算法软件的.NET例子；
B：某国外开源机器学习算法的.NET实现博客例子；
C：微软研究人员机器学习算法实现的例子；
D：Python开源社区一个机器学习算法py实现的.NET版本；
第一段代码来自微软剑桥研究院，是Infer.NET的一个Demo代码
第二段代码来自开源机器学习组件Accord.NET Framework的实例代码
打赏支持我写出更多好文章，谢谢！
打赏支持我写出更多好文章，谢谢！
任选一种支付方式
关于作者：
可能感兴趣的话题
Interesting, and useful sometimes.
关于伯乐在线博客
在这个信息爆炸的时代，人们已然被大量、快速并且简短的信息所包围。然而，我们相信：过多“快餐”式的阅读只会令人“虚胖”，缺乏实质的内涵。伯乐在线内容团队正试图以我们微薄的力量，把优秀的原创文章和译文分享给读者，为“快餐”添加一些“营养”元素。
新浪微博：
推荐微信号
（加好友请注明来意）
– 好的话题、有启发的回复、值得信赖的圈子
– 分享和发现有价值的内容与观点
– 为IT单身男女服务的征婚传播平台
– 优秀的工具资源导航
– 翻译传播优秀的外文文章
– 国内外的精选文章
– UI,网页，交互和用户体验
– 专注iOS技术分享
– 专注Android技术分享
– JavaScript, HTML5, CSS
– 专注Java技术分享
– 专注Python技术分享
& 2018 伯乐在线本文是一套面向C# programmer 和C# developer 进行开发所应遵循的开发规范。
按照此规范来开发C#程序可带来以下益处：
&&&&&&&&& 代码的编写保持一致性，
&&&&&&&&& 提高代码的可读性和可维护性，
&&&&&&&&& 在团队开发一个项目的情况下，程序员之间可代码共享
&&&&&&&&& 易于代码的回顾，
本规范是初版，只适用于一般情况的通用规范，并不能覆盖所有的情况。
2. 文件组织
2.1 C# 源文件
类名或文件名要简短，不要超过2000LOC，将代码分割开，使结构清晰。将每个类放在一个单独的文件中，使用类名来命名文件名（当然扩展名是.cs）。这种约定会使大家工作更简单。
2.2 目录设计
为每一个命名空间创建一个目录。（用MyProject/TestSuite/TestTier作为MyProject.TestSuite.TestTier的路径，而不用带点的命名空间名做路径）这样可以更容易地将命名空间映射到目录层次划分。
当一个表达式超过一行时，根据这些通用原则进行处理：
&&&&&&&&& 在逗号后换行。
&&&&&&&&& 在操作符后换行。
&&&&&&&&& 在高层换行而不要在低层处换行。
&&&&&&&&& 折行后对齐上一行语句同一层的表达式起始位置。
方法调用换行示例：
longMethodCall(expr1, expr2,
&&&&&&&&&&&&&&&expr3, expr4, expr5);
算术表达式换行示例：
var = a * b / (c - g + f) +
不好的格式&&应避免：
var = a * b / (c - g +
&&&&&&f) + 4 *
推荐使用第一种方法，因为是在括号表达式之外折行（高层次折行原则）。注意要用制表符到缩进的位置，然后用用空格到折行的位置。在我们的例子中是：
& var = a * b / (c - g + f) +
& ......4 *
'&'表示是制表符，'.'表示是空格符。（制表符后是空白是用制表符缩进）。一个好的编码习惯就是在所用的编辑器中显示制表符和空格符。
利用空格进行缩进从未有过统一的标准。一些人喜欢用两个空格，一些人喜欢用四个空格而还有一些人喜欢用八个空格，甚至有的人喜欢用更多的空格。好的做法是用制表符。制表符有一些优点：
&&&&&&&&& 每个人都可以设置他们自己喜欢的缩进层级。
&&&&&&&&& 它仅仅是1个字符而不是2，4，8等等，因此它将减少输入（甚至因为自动缩进，有时你不得不手工设置缩进或取消设置，等等诸如此类的操作）。
&&&&&&&&& 如果你想增加或减少缩进，可以标记一块，使用Tab增加缩进层级而用Shift-Tab减少缩进层级。这几乎对于任何文本编辑器都是适用的。
这里，我们定义制表符为标准缩进符。
不要用空格缩进&用制表符！
4.1 块注释
块注释通常应该是被避免的。推荐使用///注释作为C#的标准声明。如果希望用块注释时你应该用以下风格：
因为样可以为读者将注释块与代码块区分开。虽然并不提倡使用C风格的单行注释，但你仍然可以使用。一旦用这种方式，那么在注释行后应有断行，因为很难看清在同一行中前面有注释的代码：
/* blah blah blah */
块注释在极少情况下是有用的。通常块注释用于注释掉大的代码段。
4.2 单行注释
你应该用//注释风格&注释掉&代码（快捷键，Alt+/）。它也可以被用于代码的注释部分。
单行注释被用于代码说明时必须缩进到相应的编进层级。注释掉的代码应该放在第一行被注释掉以使注释掉的代码更容易看清。
一条经验，注释的长度不应该超过被解释代码的长度太长，因为这表示代码过于复杂，有潜在的bug。
4.3 文件注释
在.net 框架，Microsoft 已经介绍了一个基于XML 注释的文件。这些文件是包括XML 标签的正规的单行的C#注释。他们遵循单行注释的模式：
/// &summary&
/// This class...
/// &/summary&
多行XML 注释遵循这种模式：
/// &exception cref=&BogusException&&
/// This exception gets thrown as soon as a
/// Bogus flag gets set.
/// &/exception&
为了被认作是XML注释行，所有的行都必须用三个反斜线开始。标签有以下两类：
&&&&&&&&& 文件说明项
&&&&&&&&& 格式/参考
第一类包括像&summary&, &param& or &exception&的标签。描述一个程序的API元素的这些文档说明项必须写清楚以方便其他程序员。如上面的多行注释示例所示，这些标签通常带有名称或cref属性。编译器会检查这些属性，所以它们必须是有效、正确的。第二类用诸如&code&, &list& or &para&标签，用于控制备注说明的布局。
文件可以用&文件&菜单中的&创建&菜单产生。文件以HTML格式产生。
5.1 每行的声明数
推荐每行只有一个声明，因为它可以方便注释。
// indentation level
// size of table
当声明变量时，不要把多个变量或不同类型的变量放在同一行，例如：
int a, //What is 'a'? What does 'b' stand for?
上面的例子也显示了变量名不明显的缺陷。当命名变量时要清晰。
5.2 初始化
局部变量一旦被声明就要初始化。例如：
string name = myObject.N
int val = time.H
注意：如果你初始化一个dialog，设计使用using语句：
using (OpenFileDialog openFileDialog = new OpenFileDialog()) {
5.3 类和接口声明
当编写C#类和接口时，应遵循以下格式化规则：
&&&&&&&&& 在方法名和圆括号&(&开始它的参数列表之间不要使用空格。
&&&&&&&&& 在声明语句的下一行以大括号"{"标志开始。
&&&&&&&&& 以"}"结束，通过它自身的缩进与相应的开始标志匹配。
Class MySample : MyClass, IMyInterface
&&&&&&&&int myI
&&&&&&&&public MySample(int myInt)
&&&&&&&&this.myInt = myI
&&&&&&&&void Inc()
&&&&&&&&&&&&&&&&++myI
&&&&&&&&void EmptyMethod()
对于一个大括号的位置参考10.1部分。
6.1 简单语句
每行都应该只包含一条语句。
6.2 返回语句
一个返回语句不要用最外围圆括号。不用：
return (n * (n + 1) / 2);
用： return n * (n + 1) / 2;
6.3 If, if-else, if else-if else 语句
if, if-else and if else-if else 语句看起来应该像这样：
if (condition) {
DoSomething();
if (condition) {
DoSomething();
DoSomethingOther();
if (condition) {
DoSomething();
} else if (condition) {
DoSomethingOther();
DoSomethingOtherAgain();
6.4 for / foreach 语句
一个for语句应该如下形式：
for (int i = 0; i & 5; ++i) {
或者放置一行（考虑用一个while语句代替）
for ( update) ;
foreach语句应该像下面所示 :
foreach (int i in IntList) {
注意：在一个循环中，即使只有一个语句通常也用括弧括起来。
6.5 While/do-while 语句
一个while语句应该写成如下形式：
while (condition) {
一个空while语句应该是以下格式：
while (condition) ;
一个do-while语句应该是如下格式：
} while (condition);
6.6 Switch 语句
一个switch语句应该如下格式：
switch (condition) {
6.7 Try-catch 语句
一个try-catch statement语句应该遵循以下格式：
} catch (Exception) {}
} catch (Exception e) {
} catch (Exception e) {
} finally {
空行提高可读性。它们分开那些逻辑上自身相关联的代码块。两行空格行应该用于以下之间：
&&&&&&&&& 一个源文件的逻辑段。
&&&&&&&&& 类和接口定义（每个文件只定义一个类或接口以避免这种情况）。
一个空格行应该总是被用于以下之间：
&&&&&&&&& 方法
&&&&&&&&& 属性
&&&&&&&&& 一个方法中的局部变量和它的第一条语句
&&&&&&&&& 一个方法中的逻辑段为了提高可读性。注意空白行必须被缩进因为它们包括一条语句这使得插入这些行更容易。
7.2 内部空格
在一个逗号或一个分号之后应该由一个空格，例如：
TestMethod(a, b, c); 不要用： TestMethod(a,b,c)
TestMethod( a, b, c );
单个空格包围操作符（除了像加的一元操作符和逻辑非），例：
a = // don't use a=b;
for (int i = 0; i & 10; ++i) // don't use for (int i=0; i&10; ++i)
// for(int i=0;i&10;++i)
7.3 表格格式化
行的一个逻辑块应该作为一个表格被格式化：
string name = "Mr. Ed";
int myValue = 5;
Test aTest = Test.TestY
对于表格的格式化用空格而不用制表符因为在某些制表符缩进设置会使表格格式化看起来是很奇怪。
8. 命名习惯
8.1 大写格式
8.1.1 Pascal Casing
习惯大写每个单词的第一个字母（就像在TestCounter）。
8.1.2 Camel Casing
习惯除了第一个单词外大写每个单词的第一个字母例如testCounter。
8.1.3 全大写情况
对于只有一两个字符缩写组成的标识符才用全大写的情况。有三个或更多个字符组成的标识符应该用Pascal情况代替。例如：
public class Math
public const PI = ...
public const E = ...
public const feigenBaumNumber = ...
8.2. 命名指导方针
通常根据指导方针在名字和命名内用低线字符对Hungarian 符号来说被认为是坏习惯。
Hungarian 符号是一组应用于命名来映射变量类型的前缀和后缀。这种命名风格在早期的Windows程序中被广泛应用，但现在被取消了至少不提倡了。如果你遵循这个指南用Hungarian 符号是不允许的。
但要记住一个好的变量名描述了语义而不失类型。
对于这个规则有个例外就是GUI编码。包括像按钮（buttton）的GUI元素，所有领域和变量名都应该带有它们类型名的后缀不是缩写。例如：
System.Windows.Forms.Button cancelB
System.Windows.Forms.TextBox nameTextB
8.2.1 类命名指导方针
&&&&&&&&& 类命名必须是名词或名词短语。
&&&&&&&&& UsePascal 情况参考8.1.1
&&&&&&&&& 不要用任何类前缀
8.2.2 接口命名指导方针Guidelines
&&&&&&&&& 用可以描述行为的名词或名词短语或形容词命名接口。（例如IComponent 或 IEnumberable）
&&&&&&&&& 用Pascal情况（参考8.1.1）
&&&&&&&&& 用I作为名字的前缀，它应该紧跟一个大写字母（接口名的第一个字母）
8.2.3 枚举命名指导方针
&&&&&&&&& 用Pascal情况命名枚举值名字和类型名字
&&&&&&&&& 枚举类型和枚举值不要前缀
&&&&&&&&& 对于枚举用单一名字
&&&&&&&&& 对于位领域用复数名字
8.2.4 只读和常量命名
&&&&&&&&& 用名词，名词短语或名词的缩写命名静态领域
&&&&&&&&& 使用Pascal 情况（参考8.1.1）
8.2.5 参数/非常量领域命名
&&&&&&&&& 一定要用描述性名字，应该能够足够表现变量的意义和它的类型。但一个好的名字应该基于参数的意义。
&&&&&&&&& 使用Camel情况（参考8.1.2）
8.2.6 变量命名
&&&&&&&&& 计数变量当用在琐碎的计数循环式更适宜叫i, j, k, l, m, n。（参考10.2例如对全局计数的更智能命名等等）&
&&&&&&&&& 使用Camel情况（参考8.1.2）
8.2.7 方法命名
&&&&&&&&& 用动词或动词短语命名方法。
&&&&&&&&& 使用Pascal（参考8.1.2）
8.2.8 属性命名
&&&&&&&&& 用名词或名词短语命名属性
&&&&&&&&& 使用Pascal 情况（参考8.1.2）
&&&&&&&&& 考虑用与其类型相同的名字命名一个属性
8.2.9 事件命名
&&&&&&&&& 用事件处理器后缀命名事件处理器
&&&&&&&&& 用sender 和 e命名两个参数
&&&&&&&&& 使用Pascal情况（参考8.1.1）
&&&&&&&&& 用EventArgs 后缀命名事件参数
&&&&&&&&& 用现在和过去时态命名有前缀和复制概念的事件名字。
&&&&&&&&& 考虑用一个动词命名事件。
8.2.10 大写总结
Class / Struct
Pascal Casing
Pascal Casing
Starts with I
Enum values
Pascal Casing
Pascal Casing
Pascal Casing
Exception class
Pascal Casing
End with Exception
public Fields
Pascal Casing
Pascal Casing
Pascal Casing
Pascal Casing
Protected/private Fields
Camel Casing
Parameters
Camel Casing
9. 编程习惯
9.1 可见性
不要任何公共实例或类变量，让它们为私有的。对于私有成员最好不用&private&作修饰语什么都不写。私有是默认情况，每个C#程序员都应该知道这一点。
用属性代替。你可以用公共静态（或常量）对于这个规则是以例外，带它不应该是规则。
9.2 没有&幻&数
不要用幻数，也就是在源代码中直接用常数值。替代这些后者以防变化（比方说，你的应用程序可以处理3540用户代替427你的代码在50行中通过分散25000LOC）是错误和没有收益的。声明一个带有数的常量来代替：
public class MyMath
public const double PI = 3.14159...
10. 编码举例
10.1 Brace placement example
namespace ShowMeTheBracket
public enum Test {
public class TestMeClass
public Test Test {
void DoSomething()
if (test == Test.TestMe) {
//...stuff gets done
//...other stuff gets done
括弧应该在以下情况之后以新行开始：
&&&&&&&&& 命名空间声明（注意这在0.3版本中是新添的与0.2版本不同）
&&&&&&&&& 类/接口/结构声明
&&&&&&&&& 方法声明
10.2 变量命名举例
for (int i = 1; i & ++i) {
meetsCriteria[i] =
for (int i = 2; i & num / 2; ++i) {
int j = i +
while (j &= num) {
meetsCriteria[j] =
for (int i = 0; i & ++i) {
if (meetsCriteria[i]) {
Console.WriteLine(i + " meets criteria");
try intelligent naming :
for (int primeCandidate = 1; primeCandidate & ++primeCandidate)
isPrime[primeCandidate] =
for (int factor = 2; factor & num / 2; ++factor) {
int factorableNumber = factor +
while (factorableNumber &= num) {
isPrime[factorableNumber] =
factorableNumber +=
for (int primeCandidate = 0; primeCandidate & ++primeCandidate)
if (isPrime[primeCandidate]) {
Console.WriteLine(primeCandidate + " is prime.");
注意：索引变量通常叫i, j, k 等等。但Note: Indexer variables generally should be called i, j, k etc. But 万一像这样，使得重新考虑这个原则更有意义。一般来说，当同一个计数器或索引器被重用，给它们有意义的名字。
阅读(...) 评论()请问在C#中，winfrom开发里怎么实现一个表格啊？代码尽量写注释啊！谢谢！_百度知道
请问在C#中，winfrom开发里怎么实现一个表格啊？代码尽量写注释啊！谢谢！
那位高手，帮我写一个用C#连接SQL 2000并读出一两个字段。代码尽量写注释，我不要通过数据绑定的。是人工书写访问到数据库的。谢谢。高手门去那里了？
我有更好的答案
楼上瞎说p啊，没看见楼主说的是winform吗？用DataGridView控件。
采纳率：23%
用DataGridView控件。
关注！GridView控件是数据控件，用来显示操作数据的，显示的形式就是表格。
为您推荐：
其他类似问题
winfrom的相关知识
换一换
回答问题，赢新手礼包
个人、企业类
违法有害信息,请在下方选择后提交
色情、暴力
我们会通过消息、邮箱等方式尽快将举报结果通知您。求C#代码注释 谢谢！！_百度知道
求C#代码注释 谢谢！！
求C#代码注释 谢谢！！
后天就要答辩了，程序不是我自己做的希望高手给我翻译下代码的含义，我上台就照你的说！！！
以下代码是表现层的前台部分代码 希望高手可以逐行解释下
界面描述：前台界面是“察看请假申请记录” Button1_Click是界面上的“搜索”...
我有更好的答案
DateTime start = Calendar1.SelectedD //创建一个时间对象，值是时间控件1中选择的时间DateTime end = Calendar2.SelectedD //同上Session[&start&]= //把选择的时间放在Session里面Session[&end&]= GridView1.Visible = //把GridView控件显示出来
采纳率：34%
现在的大学生啊~~，哎。。。。你什么专业的？
为您推荐：
其他类似问题
换一换
回答问题，赢新手礼包
个人、企业类
违法有害信息,请在下方选择后提交
色情、暴力
我们会通过消息、邮箱等方式尽快将举报结果通知您。}