编程术语方面的请教，长期请教，还请各位指点

kenadams001

一点个人看法，仅供参考。

代码注释最好开门见山，第一句话应该说明整个类，方法或者重要程序段的主要目的。上面的代码片断最好有一个总结性注释。

如果是十分重要的算法，对于每个循环和判断条件最好都注释说明。但是注释的内容最好是程序员的思路的编码意图，而不是对代码的解释。比如第一句注释：

// Get the college's branchs.
aryBranchInfos = ws.GetBranchsBycollegeId(collegeInfo.CollegeId);

这个注释没有问题，但是也没有给读者带来更多的信息。

另外， if (aryStudentClassInfos.Length > 0) 没有给出注释，从上下文看不出这个条件判断有什么意义。

一般来说，对于成熟算法的具体实现细节可以不用详细说明，代码本身表达不清楚的算法再加一些注释。你上面的例子是一个片断，无法了解具体业务，大概是要创建一个树结构，把branch和studentclass根据业务规则加到相应节点里。

但是 BranchInfo branch = aryBranchInfos; 没有给出注释。aryBranchInfos 从上面看应该是数组，这里却给了一个类，显然需要说明一下目的和意图。

还有一个重要的判断语句if (!tvwLeft.Nodes.ContainsKey(strStudentTypeNodeKey))也没有给出注释，所以读者还要去看tvwleft是什么才能理解什么条件的studentclass才可以加到branch里。

ztchen

非常感谢楼上的朋友，指出的地方都很对，一看就知道是比较有功力的。

我这里摘录的是片断代码，想让大家看看在代码中我写的注释，所以 if (aryStudentClassInfos.Length > 0) 是有用的判断，因为后面除了遍历该数组以外还有其他执行代码，否则会有问题。

另，BranchInfo branch = aryBranchInfos; 其实应该是BranchInfo branch = aryBranchInfos(i);，<-这里我用括号了，本应该是方括号，但发帖子的时候方括号会给转义，所以就变成莫名的代码了。


整体来说，在class 和 function里我都会写上基本的思路，怎奈现在英语水平有限，不能表达更多，所以就没有贴出来，之后要么我贴出来献丑一下，大家不要见笑，呵呵。

kenadams001

楼主客气了。我没有注意到楼主是要关注注释的英文表达。前面说的都是注释方法，关于英语我觉得还是简明易懂为主，核心应该是描述编码思路和意图。下面是对英文的一点建议：

// Loop the array of the objects of branch and add the children nodes of the root node.
“Loop the array“ 好像没有这样写的，一般表达遍历应该是iterate through. 要是我写的话，可能会是 iterate through  all branchs in the collection, create a tree node for each branch and add the them into the colleage node.

// First of all, add the child nodes of studenttype with each college node.
一般来说注释里面最好不要有代码语言，比如变量名称studenttype。这里studenttype并不是很清楚，应该使用实际业务的说法。注释可以写成： iterate through the course collection, create a treenode for the [studenttype-使用业务名称] which belongs to [那个条件的说明]  and add them into the  branch.

// In this place, the studenttype key is composed by branchId and studenttypeId.
这句实际上在解释代码，最好说明这个key的用途。比如：combine the IDs of the current branch and student type as a key used to judge whether the current student type should be added into the current branch.

我的英文纯属一般，仅供参考。

ztchen

非常感谢楼上，不仅指出了问题，还给出了整句的示例。并且不仅仅是英语上的帮助，注释方面也很受益，对我来说非常有用，像Loop等的都可能都是中国式英语，我确实是要表达为遍历的意思，但自己都是靠单词面上的意思来写的，自己估计也不规范，所以就需要在澳洲的同行帮我指出问题了。
studenttype其实不是变量名称，我只是想表达学生类型，不过变量名和数据库字段名都是这么命名的，所以就直接写了。

这些我以后会逐步改正，再次感谢！

bffbffbff

原帖由 ztchen 于 2007-12-2 22:17 发表
非常感谢楼上，不仅指出了问题，还给出了整句的示例。并且不仅仅是英语上的帮助，注释方面也很受益，对我来说非常有用，像Loop等的都可能都是中国式英语，我确实是要表达为遍历的意思，但自己都是靠单词面上的意思来 ...

Loop is not a chinglish really...

For similar context, please google "loop through" + c# + keyword, and you'll have some ideas.

degra

原帖由 bffbffbff 于 2007-12-3 17:21 发表


Loop is not a chinglish really...

For similar context, please google "loop through" + c# + keyword, and you'll have some ideas.

bffbffbff

原帖由 gandu 于 2007-12-3 17:25 发表

汗...

ztchen

原帖由 bffbffbff 于 2007-12-3 17:21 发表


Loop is not a chinglish really...

For similar context, please google "loop through" + c# + keyword, and you'll have some ideas.

谢谢，请问你怎么写的？

[ 本帖最后由 ztchen 于 2007-12-5 03:29 编辑 ]

ztchen

很久没贴代码，都到新地方来了，贴一些自己写的注释，继续话题，大家帮我看看写得是否正确？
我比较困惑的是一般用口语还是书面习惯写程序注释？

/// <summary>
        /// Get or set the activate flag of the user object.
        /// </summary>
        public bool ActivateFlag
        {
            get
            {
                return _ActivateFlag;
            }
            set
            {
                _ActivateFlag = value;
            }
        }

/// <summary>
        /// Get or set the real name of the users.
        /// </summary>
        public string UserRealName
        {
            get
            {
                return _UserRealName;
            }
            set
            {
                _UserRealName = value;
            }
        }

魔头

注释写那么罗嗦复杂干吗

=.=

miles

注释不规范，原则上应该把函数的用途，参数的解释以及返回值含义描述清楚，以便于将来可以通过文档软件自动生成程序文档。关键在于容易理解，用词不必规范

ztchen

恩，不过这个是简单属性。可能写得比较少。但我不确定应该怎样书写。就像楼上说的，将来肯定是要生成说明文档的，那么不就是要书面写法，而不是口语化的写法了？