Clean Code 笔记 之 第四章 如何应用注释
继上一篇笔记之后,今天我们讨论一下 代码中是存在注释是否是一件好的事情。
在我们开发的过程中讲究“名副其实,见名识意”,这也往往是很多公司的要求,但是有了这些要求是不是我们的代码中如果存在注释是不是意味着我们的 函数,变量,以及类 的命名就不符合了“名副其实,见名识意”。
我们先区分一下注释的类别,注释一般分为以下几种:
- 1, 单行注释
- 2, 多行注释
- 3, 文档注释
- 4, #region 折叠注释,可以将 代码折叠
注释的类别
1, 单行注释:
在以 “//” 开头,用以说明一行代码的作用放置位置 看习惯或者公司要求合理就行。常用于函数内部,在很多的开源代码中文件的头部我同样见到很多人使用单行注释进行说明,灵活就好。
体现形式如下:
public List<string> getVipUserNameByUserType() { // Vip user name list var vipUserNames = new List<string>(); foreach (var user in Users) { if (user.Type = "VIP") vipUserNames.Add(user.Name); } return vipUserNames; }
2, 多行注释:
以“/*”开头 “*/” 结尾 常用于描述说明一段代码以及类注释或者说代码块常用于文件的顶部。说明作者信息,时间如果是开源的这包含开源的更多说明。
通常使用如下:
/* * 作者:〈版权〉 * 描述:〈描述〉 * 创建时间:YYYY-MM-DD * 作用: */
3, 文档注释:
也就是常用的XML 注释:它的说明性更加的强烈,多用于类以及函数上,当然属性上同样可以使用:
如下所示:
/// <summary> /// MyClass /// </summary> public class MyClass { /// <summary> /// MyProperty /// </summary> public int MyProperty { get; set; } /// <summary> /// MyMethod /// </summary> public void MyMethod(){ } }
以下是官方建议的文档标记 点击标签会制动跳转
4, #region : 折叠注释,常用于描述多个函数的基本作用
书中最喜欢的话
好的注释不能美化糟糕的代码,真正好的注释是你想尽办法不去谢的注释。怀注释都是糟糕代码的支撑或借口,或者是对错误决策的修正。
下面看一个例子
//Check to see if the employee is eligible for full benefits ()If((employee.flags & HOURLY_FLAG)&& (employee.age>)) ()If(employee.isEligibleForFullBenefits())) 这两个你更喜欢哪个
好的注释的特征:
1:表示法律信息(这样的注释一般出现在文档顶部说明作用以及协议)
// Copyright (c) .NET Foundation. All rights reserved // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
2:提供信息的注释(指无法通过命名提供信息如要 注释辅助的)
public void ConfigureServices(IServiceCollection services) { // These two middleware are registered via an IStartupFilter in UseIISIntegration but you can configure them here. services.Configure<IISOptions>(options => {}); }
3:对意图的解释
4: 警示:告知其他人会出现某种后果的注释
5: TODO注释: 主要描述应该做的目前还没有做的事情。
6: 放大:提示不合理之物的重要性。
应避免的注释
应该避免以下几点:
1: 误导性注释
2: 日志式注释
3: 废话注释
4: 标记位置的注释
5: 括号后的注释
6: 归属与签名
7: 注释掉的代码
8: Html 注释
以上没有一一举例的原因是我的PPT是一份演示的PPT,里面很多公司的代码不便贴出,抱歉。
不足之处还请指出
最新文章
- 【AR实验室】OpenGL ES绘制相机(OpenGL ES 1.0版本)
- 下载本 WebEnh博客 安卓APP
- 鹏程网用户管理系统学习(2016-07-18 by 徐鹏)
- 【技巧】为ComboBox添加自动提示
- 值不能为 null 或为空。参数名: linkText
- linux 文件系统的管理 (硬盘) 工作原理
- DevExpress 控件使用之GridControl基本属性设置
- 2020: [Usaco2010 Jan]Buying Feed, II
- 使用NPOI写入Excel数据(ASP.NET)
- Web Components(续)
- debugger
- C++11 线程并发
- sql server 复制、镜像常见故障处理
- spring boot: ConfigurationProperties
- Qt,Qt/E,Qtopia Core, Qtopia之间的区别和联系
- HDU 4529 郑厂长系列故事——N骑士问题 状压dp
- Python之旅:并发编程之IO模型
- Linux下安装jdk1.6
- HDU 6357.Hills And Valleys-字符串非严格递增子序列(LIS最长非下降子序列)+动态规划(区间翻转l,r找最长非递减子序列),好题哇 (2018 Multi-University Training Contest 5 1008)
- [Apollo Server] Get started with Apollo Server