c#书写规范之---注释
注释
软件文档以两种形式存在:外部的和内部的。外部文档(如规范、帮助文件和设计文档)在源代码的外部维护。内部文档由开发人员在开发时在源代码中编写的注释组成。
不考虑外部文档的可用性,由于硬拷贝文档可能会放错地方,源代码清单应该能够独立存在。外部文档应该由规范、设计文档、更改请求、错误历史记录和使用的编码标准组成。
内部软件文档的一个难题是确保注释的维护与更新与源代码同时进行。尽管正确注释源代码在运行时没有任何用途,但这对于必须维护特别复杂或麻烦的软件片段的开发人员来说却是无价的。
以下几点是推荐的注释方法:
- 如果用 C# 进行开发,请使用 XML 文档格式,如下面方法的注释:
/// <summary>
/// 得到某人的年龄
/// </summary>
/// <param name="userName">用户名</param>
/// <returns>用户年龄</returns>
public int GetUserAge(string userName)
{
//
//此处写你的程序代码
//
}
- 修改代码时,总是使代码周围的注释保持最新。
- 在每个例程的开始,提供标准的注释样本以指示例程的用途、假设和限制很有帮助。注释样本应该是解释它为什么存在和可以做什么的简短介绍。
- 避免在代码行的末尾添加注释;行尾注释使代码更难阅读。不过在批注变量声明时,行尾注释是合适的;在这种情况下,将所有行尾注释在公共制表位处对齐。
- 避免杂乱的注释,如一整行星号。而是应该使用空白将注释同代码分开。
- 避免在块注释的周围加上印刷框。这样看起来可能很漂亮,但是难于维护。
- 在部署之前,移除所有临时或无关的注释,以避免在日后的维护工作中产生混乱。
- 如果需要用注释来解释复杂的代码节,请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码,而应该重写它。尽管一般不应该为了使代码更简单以便于人们使用而牺牲性能,但必须保持性能和可维护性之间的平衡。
- 在编写注释时使用完整的句子。注释应该阐明代码,而不应该增加多义性。
- 在编写代码时就注释,因为以后很可能没有时间这样做。另外,如果有机会复查已编写的代码,在今天看来很明显的东西六周以后或许就不明显了。
- 避免多余的或不适当的注释,如幽默的不主要的备注。
- 使用注释来解释代码的意图。它们不应作为代码的联机翻译。
- 注释代码中不十分明显的任何内容。
- 为了防止问题反复出现,对错误修复和解决方法代码总是使用注释,尤其是在团队环境中。
- 对由循环和逻辑分支组成的代码使用注释。这些是帮助源代码读者的主要方面。
- 在整个应用程序中,使用具有一致的标点和结构的统一样式来构造注释。
- 用空白将注释同注释分隔符分开。在没有颜色提示的情况下查看注释时,这样做会使注释很明显且容易被找到。
c#书写规范之---注释相关推荐
- Python(1)--代码书写规范和注释
1.Python不需要在语句末尾加分号(;)表示语句结束,直接换行即可. 2.Python使用冒号(:)用来标识语句块的开始,块中的每一个语句都是缩进的且他们的缩进量相同. 3.Python使用缩进来 ...
- doxygen 注释规范_编程规范 - doxygen注释规范示例(C++)
doxygen注释规范示例(C++) doxygen能根据code的注释自动生成code的帮助文档,并且doxygen是一个跨平台的开源的软件,但是要生成帮助文档,code内的注释必须按一定规则书写. ...
- CSS 样式书写规范
可能不同团队都有各自的规范,又或者很多人在写 CSS 的时候还是想到什么就写什么,不存在太多的约束. 我觉得 CSS 代码规范还是有存在的必要的,尤其是在团队配合,多人协作下,规范就显得尤为重要. 本 ...
- 推荐大家使用的CSS书写规范、顺序
推荐大家使用的CSS书写规范.顺序 CSS书写顺序 1.位置属性(position, top, right, z-index, display, float等) 2.大小(width, height, ...
- html css js书写规范
无论是从技术角度还是开发视角,对于web前端开发规范文档都有一定规范,本文就css3和html5的发展前景总结了一系列的web开发文档,仅供大家参考. 规范目的: 为提高团队协作效率, 便于后台人员添 ...
- css命名规范和书写规范
1.位置属性(position, top, right, z-index, display, float等) 2.大小(width, height, padding, margin) 3.文字系列(f ...
- (转)CSS书写规范、顺序
原文地址 写了这么久的Css,但大部分前端er都没有按照良好的CSS书写规范来写CSS代码,这样会影响代码的阅读体验,这里总结一个CSS书写规范.CSS书写顺序供大家参考,这些是参考了国外一些文章以及 ...
- TypeScript的书写规范(TSLint)配置修改
新版Angular中使用的Typescript书写规范非常恼人,比如默认会启用no-trailing-whitespace这样的选项.官方对此的说明是为了配合GIT的使用规范. 虽然这种规则在规范程序 ...
- day01 js三种导入html的方法、js书写规范、变量的基本使用、变量提升
昨天是初学js的第一天,为什么今天才写,我觉得这样可以帮助我复习昨天的知识,加深对js的理解. 我之前学过java的,昨天转入js的学习,对js略有些体会和大家分享下,js刚入门感觉js相对于java ...
最新文章
- nodejs安装及npm模块插件安装路径配置
- PS5穿越云层3D文字
- [分享]2007年创业给我们的提示
- I/O模型之一:Unix的五种I/O模型
- 一. DotNet MVC4.0+EasyUI Web简单框架-前言
- 趣头条将获得阿里1.71亿美元的可转债,为期三年...
- 程序员面试【Brainteasers】
- nodejs中httpserver的安装和使用
- “智慧北京”让生活更美好
- JavaScript frame跨域获取元素、修改元素属性、调用其他frame页面方法
- SLF4J 教程(自由在各种log中切换)
- php 接口说明文档,phpwind文章中心接口说明
- Java VM –提防YoungGen空间
- 【好文链接】什么是最小二乘法?
- Linux学习笔记 -- rpm 与 shell 编程
- 计算机还原取消,如何取消开机一键还原F11选项?
- 【蓝桥杯集训100题】scratch辨别质数合数 蓝桥杯scratch比赛专项预测编程题 集训模拟练习题第15题
- 听说你想学Python爬虫?我从零教你啊
- IDEA 2017.3.4 破解到2099年方法
- JAVA高级---(2)15分钟入门JVM底层原理
热门文章
- 软硬链接、文件删除原理、linux中的三种时间、chkconfig优化
- java-web——第十课 session
- WCF如何通过契约加编码方式调用
- SQLServer学习笔记系列6
- Windows 8开机时间
- button,submit, image的区别 点onclick后隐藏行
- ofdma技术_科普:何为第六代WiFi技术?你家也可以轻松实现1.6G每秒的网速
- python 屏幕录制_Python实现屏幕录制功能的代码
- iphone屏幕录制_今日应用:iPhone 不越狱也可以录制屏幕了
- matlab 比例谐振控制器,比例谐振控制的一种实现(含代码)