给代码写个好注释

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

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;
}