自己总结的C#编码规范--5.如何写好注释篇
本文是读完前言中提到的几本书后,结合自身的想法总结出来的如何写好注释的一些比较实用的方法。
另外本文是上一篇 注释篇 的一个补充
如何写好注释
避免使用不明确的代词
有些情况下,"it", "this"等代词指代很容易产生歧义,最安全的方式是不要使用将所有可能产生歧义的代词替换成实际指代的词。
如://Insert the data into the cache,but check if it's too big first.
"it"是指"data"还是"cache"? 在读完剩下的代码前谁也不知道指代的是谁。那还要注释做什么?替换成要指代的词后读者就可以直接了当的知道接下来的代码要做什么了。
//Insert the data into the cache,but check if the data is too big first.
精确描述方法的行为
注释一定要精确的描述方法的行为。避免由于注释不准确而造成的误调用。
如你写了一个方法统计文件中的行数
//Return the number of lines in this file
public long CountLinesInFile(string fileName)
上面的注释不是很精确,因为有很多定义行的方式,下面几种情况这个方法的返回值无法根据注释快速的判断出来。
- ""(空文件)——0或1行?
- "hello"——0或1行?
- "hello\n"——1或2行?
- "hello\n\r world\r"——2、3或4行?
假设该方法的实现是统计换行符的(\n)的个数,下面的注释就要比原来的注释更好些。
//Count how many newline symbols('\n') are this file
这条注释包含更多的信息。读者可以知道如果没有换行符,这个函数会返回0。读者还知道回车符(\r)会被忽略。
用输入输出例子来说明特殊的情况
对于注释来讲,一个精挑细选的例子比千言万语还要有效,而且更加直白有效,阅读速度更快。
如: /// <summary>
/// Remove the suffix/prefix of charsToRemove from the input source
/// </summary>
public string StripPrefixAndSuffix(string source, string charsToRemove)
这条注释不是很精确,因为它不能回答下面的问题
- 是只有按charsToRemove中顺序的字符才会被移除,还是无序的charsToRemove也会被移除?
- 如果在开头和结尾有多个charsToRemove会怎样?
而一个好例子就可以简单直白的回答这些问题:
/// <summary>
/// Example: StripPrefixAndSuffix("abbayabbazbaba","ab") returns "yababz"
/// </summary>
适当的使用具名函数
假设你看见这样的函数调用:
ConnectMailServer(100,false);
因为直接传入的是数值和bool值,使得这个调用很难理解,在这种情况下可以使用C#的具名函数以便代码阅读者快速知道这两个参数的含意。
假设函数是这样的:public void ConnectMailServer(int timeout_s, bool useEncryption)
那我们可以这样使用具名函数:
ConnectMailServer(timeout_s: 100, useEncryption: false);
代码阅读者一眼就能看出这两个参数的作用。
使用通用专有名词
代码的阅读者和调用者都是程序员,程序员间有大量的专有名词可以用来描述一些模式和解决方案,使用这些词,可以简单明了的阐述你代码的含意。
假设你原来的注释是这样的:
那么你完全可以简单的说:
//This class acts as a caching layer to the database.
程序员一看caching layer就明白这个类是做什么的了。而且就算新手不明白,你的注释也很难给他讲明白的,还不如给他个关键词,让他自己去Google或向别人请教。这样的效果比你的注释会好的多。
更新代码时记得更新注释
再好的注释也会随着内容的更改而变得越来越没有意义,有时候甚至会对读者造成误导,产生不必要的bug。所以在更改代码后,记得要更新所更改代码的注释,使其表达最新代码的含意。
只有能让别人读懂的注释才是合格的注释
当自己不确定自己的注释是否合格时,请周围的同事读下你的注释,看他读完注释后说出的想法是否是你想要表达的,是否有信息遗漏和误解等。
自己总结的C#编码规范--5.如何写好注释篇的更多相关文章
- 官方Java编码规范
先由Sun制定,之后Sun把Java卖给了Oracle,最后就成了Oracle制定的了.但是版本比较旧了,停留在1999年. 相比Google的编码规范,罪名写的却别就是Sun采用的是4个空格进行缩进 ...
- Android的编码规范
一.Android编码规范 1.学会使用string.xml文件 在我看来,当一个文本信息出现的次数大于一次的时候就必须要使用string.xml 比如一个保存按钮 , 不规范写法: <Butt ...
- PHP 高级编程(1/5) - 编码规范及文档编写
PHP 高级程序设计学习笔记20140612 软件开发中的一个重要环节就是文档编写.他可以帮助未来的程序维护人员和使用者理解你在开发时的思路.也便于日后重新查看代码时不至于无从下手.文档还有一个重要的 ...
- 【原】JAVA SE编码规范
/* * 编码规范: * 1.所有的命名遵循"见名知意"的原则 * 2.所有的命名不允许使用汉字或拼音 * 3.Java的工程命名建议使用小写,比如:oa.crm.cms... * ...
- 浅谈Android编码规范及命名规范
前言: 目前工作负责两个医疗APP项目的开发,同时使用LeanCloud进行云端配合开发,完全单挑. 现大框架已经完成,正在进行细节模块上的开发 抽空总结一下Android项目的开发规范:1.编码规范 ...
- PHP编码规范PSR-2
.note-content { font-family: "Helvetica Neue", Arial, "Hiragino Sans GB", STHeit ...
- Objective-C开发编码规范【转载】
概要 Objective-C是一门面向对象的动态编程语言,主要用于编写iOS和Mac应用程序.关于Objective-C的编码规范,苹果和谷歌都已经有很好的总结: Apple Coding Guide ...
- 前端编码规范之CSS
"字是门面书是屋",我们不会去手写代码,但是敲出来的代码要好看.有条理,这还必须得有一点约束~ 团队开发中,每个人的编码风格都不尽相同,有时候可能存在很大的差异,为了便于压缩组件对 ...
- 前端编码规范之JavaScript
上次浅谈了下关于CSS的编码规范,大部分童鞋持赞同意见,仍存在一些童鞋不太理解这些规范的意义. 如果是个人或者小作坊开发,其实这些所谓的编码规范也没啥意思,因为大家写好的代码直接就给扔到网上去了,很少 ...
随机推荐
- Java并发编程基础-ReentrantLock的机制
同步锁: 我们知道,锁是用来控制多个线程访问共享资源的方式,一般来说,一个锁能够防止多个线程同时访问共享资源,在Lock接口出现之前,Java应用程序只能依靠synchronized关键字来实现同步锁 ...
- laravel 中CSS 预编译语言 Sass 快速入门教程
CSS 预编译语言概述 CSS 作为一门样式语言,语法简单,易于上手,但是由于不具备常规编程语言提供的变量.函数.继承等机制,因此很容易写出大量没有逻辑.难以复用和扩展的代码,在日常开发使用中,如果没 ...
- Eclipse搭建.C#和..NET Core环境
1.在上一篇博客中我介绍了如何使用Eclipse搭建C++.C开发环境,顺带把搭建 .NET Core 和C#也做个介绍.配置任何环境关键是找到要开发语言的编辑器和SDK.eclipse是java开发 ...
- cf29d 深搜,dfs序
#include<bits/stdc++.h> using namespace std; #define maxn 500 ]; int n,head[maxn],tot,a[maxn], ...
- Ubuntu下安装kate编辑器
Ubuntu下安装kate编辑器 Ubuntu 下安装kate编辑器 #sudo apt-get install kate 安装kconsole #sudo apt-get install kco ...
- .NoSuchBeanDefinitionException: No bean named 'userService' available
- linux 搭建testlink的问题总结
testlink问题总结 1.要求环境centos7,安装php版本5.5以上(7.1.5),mysql5.6 ,5.7测试还不行(改变挺大的5.7表结构,字段啥的待研究),apache任意版本即可 ...
- Python中的日志处理
在日常项目中,总是需要记录下一些细小信息或者错误码.错误信息的,这个时候就需要进行日志的操作.python中用于日志创建.设置和记录等功能的模块,就是logging了,下面是对其基本使用方法的介绍: ...
- dump增加的表数据
备份mysql数据库表中,增加的部分 前提条件: 备份库和正式库表结构一样: 表名不一样可以改: 备份库:192.168.1.10 正式库:192.168.1.11 获取当前"备份" ...
- alpha冲刺7/10
目录 摘要 团队部分 个人部分 摘要 队名:小白吃 组长博客:hjj 作业博客:冲刺7 团队部分 后敬甲(组长) 过去两天完成了哪些任务 界面设计.图标设计 写博客 接下来的计划 准备下周答辩 跟进进 ...