给代码写个好注释

Love The Way You Lie 2021-11-06 00:14 372阅读 0赞

注释能让代码阅读者更好的理解代码。本文介绍注释的常见类型和注意事项。

## 1.注释的类型 ##

### 1.1 记录代码版权和授权 ###

这类注释放在每一个源代码文件的开头，说明源代码的所有者，以及授权使用的许可方式。

该注释的特点：

*  首行和尾行只使用星号;
 *  中间行以缩进一个空格的星号开始;
 *  文字和星号之间使用一个空格。

/*
     * Copyright (c) 2019, Name. All rights reserved.
     */

### 1.2 生成文档 ###

这类注释用于生成文档，帮助使用者了解软件的功能，如API规范的文档。

该注释除了首行多了个星号，其它与第一种风格相同。

/**
     * {@code Context} 是与设备相关的上下文信息
     *
     * @since 1.0
     */
     public interface Context{
         ...
     }

### 1.3 解释源代码 ###

这类注释旨在帮助阅读者更好的理解代码。

该注释只使用行注释符 //

// 用户的唯一标识符
    int userId;

## 2.注释的注意事项 ##

### 2.1 更新过时的注释 ###

代码逻辑变化了，其对应的注释也要相应修改，否则会误导阅读者。如原来的函数:

// 用户id是否合法
    bool IsValid(int id) const
    {
        ...
    }

后来修改为：

// 用户id是否合法
    bool IsValid() const
    {
        ...
    }

此时，该函数还增加了userName, password等逻辑判断，不再仅仅判断id。但是原来的注释没有更新。这就很可能误导该函数的使用者。

### 2.2 去掉多余的注释 ###

如果代码本身命名恰当，结构清晰，此时重复代码语义的注释就是多余的注释。如下注释应该被去掉

class Point
    {
     public:
         // 点的构造函数
         Point();
    }

### 2.3 去掉混乱的注释 ###

混乱的注释会打乱代码的逻辑，给阅读带来困难。如下注释应该被去掉。

void Point::Divide(const float scalar) 
    {
        //if(scalar == 0)
        //  throw std::invalid_argument("cannot be zero");
        if (scalar <= 1.e-6f)
            throw std::invalid_argument("cannot be zero");
    
        mX = mX / scalar;
        mY = mY / scalar;
    }

发表评论取消回复

表情：

评论列表（有 0 条评论，372人围观）

还没有评论，来说两句吧...

相关阅读

相关优秀java程序员常用注释标记--如何写好Java代码注释。

1. IDEA 自动生成对于类中的注释，我们可以通过IDEA自动生成。如IDEA 可以通过：File->Settings->Editor->File and Cod

Bertha 。/ 2023年06月15日 06:55/ 0 赞/ 223 阅读

相关举个例子，如何写好业务代码！

你知道的越多，不知道的就越多，业余的像一棵小草！成功路上并不拥挤，因为坚持的人不多。编辑：业余草 toutiao.com/i6903053083555807

电玩女神/ 2022年10月15日 10:58/ 0 赞/ 17 阅读

相关给代码写注释时有哪些讲究？

![0D5F937FE12312312D81F17F.jpg][] 程序员的成长之路互联网/程序员/技术/资料共享 [关注][Link 1] 阅读本文大概需要 4.

客官°小女子只卖身不卖艺/ 2022年10月10日 06:12/ 0 赞/ 150 阅读

相关我的代码很好，不需要写注释

![7105fd1753368cf5a7e89dfee50cccdc.png][] > 作者 | Sheetal > > 译者 | 弯月责编 | 王晓曼有时候，我们会

比眉伴天荒/ 2022年08月28日 09:50/ 0 赞/ 180 阅读

相关给代码建个好结构

本文以一个开源项目为例，介绍如何组织一个层次分明、易于检索的文件结构。如下图是该项目的根目录： ![watermark_type_ZmFuZ3po

àì夳堔傛蜴生んèń/ 2021年11月17日 17:28/ 0 赞/ 516 阅读

相关给代码写个好声明

声明用来定义类、方法、类变量、局部变量和常量等。声明一般包含两个部分：标识符的名字和类型，如： int id; 好的声明包含以下几个原

不念不忘少年蓝@/ 2021年11月17日 08:32/ 0 赞/ 342 阅读

相关给代码起个好名字

给代码起个好名字，有助于理顺代码逻辑，提高代码的清晰度，提高开发效率。目前，比较常用的命名方法有：驼峰命名法蛇形命名法串式命名法

た入场券/ 2021年11月17日 05:48/ 0 赞/ 412 阅读

相关给代码写个好注释

注释能让代码阅读者更好的理解代码。本文介绍注释的常见类型和注意事项。 1.注释的类型 1.1 记录代码版权和授权这类注释放在每一个源代码文件的

Love The Way You Lie/ 2021年11月06日 00:14/ 0 赞/ 373 阅读

相关给代码写注释时有哪些讲究？

点击上方 [Java后端][Java]，选择设为星标优质文章，及时送达 -------------------- 如果领导给你一个项目的源码让你阅读，并理解重构代码，

不念不忘少年蓝@/ 2021年09月07日 06:00/ 0 赞/ 418 阅读

相关 16 个写代码的好习惯

每一个好习惯都是一笔财富，本文整理了写代码的16个好习惯，每个都很经典，养成这些习惯，可以规避多数非业务的bug！希望对大家有帮助哈，谢谢阅读，加油哦~ github地址，感

ゞ浴缸里的玫瑰/ 2021年09月03日 05:31/ 0 赞/ 471 阅读