文档结构  
翻译进度:已翻译     翻译赏金:0 元 (?)    ¥ 我要打赏

在代码中是否应该写注释,这是一个问题。 关于这个问题我跟我的一些家庭成员(他们也进行了一些编码,尽管其中一个仍在上中学)有了一些争论。 他们快速浏览了一些我在家里写的代码,并问我的代码注释在哪里。 当我告诉他们我不使用注释的时候,他们对我的回答感到震惊。 所以我要把我告诉他们的一些事情写下来。 什么时候把注释写入你的代码,它们有什么帮助,它们应该包含什么? 这些都是我将要回答的问题。

第 1 段(可获 1.45 积分)

正常情况下,我不会在我的代码里写注释,特别是我在工作时写的代码。当我刚开始工作时,我最先被告诉的其中一件事就是不要写注释,而且起初我还有点怀疑,但是过了一段时间后我就觉得这是有道理的。

我写的代码应该能够解释它自己。并不是说你永远不应该使用注释,只是我不需要解释一段代码要做的事情,而是应该让它成为显而易见的。如果有一段代码需要用注释来说明它是做什么的,那么我会问我自己,“这段代码是否应该成为一个单独的方法?” 这样的话,当其他人过来看到这个代码之后,他们就可以只用看下方法的名字就知道他应该做的事情。这样也有其他好处,比如方法会变得更短,因为相关的代码段将会被转移到其他地方,而且新创建的方法还可以被其他地方重用。

第 2 段(可获 2.13 积分)

尽管这是一个很简单的例子,但是我认为它应该稍微改进一点,即删除注释。

public void someRandomMethod() {
    System.out.println(totalOfAddedNumbersUpToTen());
    System.out.println(totalOfMultipliedNumbersUpToTen());
    System.out.println(totalOfSubtractedNumbersUpToTen());
}

private int totalOfAddedNumbersUpToTen() {
    int totalOfAddedNumbers = 0;
    for (int i = 1; i <= 10; i++) {
        totalOfAddedNumbers += i;
    }
return totalOfAddedNumbers;
}

private int totalOfMultipliedNumbersUpToTen() {
    int totalOfMultipliedNumbers = 1;
    for (int i = 1; i <= 10; i++) {
        totalOfMultipliedNumbers *= i;
    }
    return totalOfMultipliedNumbers;
}

private int totalOfSubtractedNumbersUpToTen() {
    int totalOfSubtractedNumbers = 0;
    for (int i = 1; i <= 10; i++) {
        totalOfSubtractedNumbers -= i;
    }
    return totalOfSubtractedNumbers;
}
第 3 段(可获 0.25 积分)

把代码分割成独立的几个方法的缺点,我想你也能看得出来,那就是代码变得更长了。但是随着你写的代码越来越复杂,这样虽然多出来额外的几行但是更加易读了,还是值得的。

我在上面讨论了关于代码块的注释,但是我真正的意思是编码者应该做的最简单的事情,也就是要给变量取有用的名字。不要只是用一个随机的字母用作变量的名字,应该给它一个合适的名字。你不应该叫它"variableA",而应该是用它自己的名字。对于变量的命名也应该是同样的思路。

第 4 段(可获 1.43 积分)
int varialbeA = 365;    // variable for the days in a year

改进这只需要几秒钟,使它更容易阅读。

int daysInAYear = 365;

当别人来浏览阅读这个代码时,他们一看到这个变量名称就会立即明白它的作用。

所以,如果你决定你还是想写一个注释---希望是在你尽量尝试不写之后,那么该怎么写呢? 保持简短,精确和易于理解。 不要写一些关于代码所做的一切的长篇累牍,也不要只写一个字。 如果它很短,它应该是一个单独的方法。 不要写出每一行代码想做的事,而是写一个代码的摘要。 最后,不要使用一些其他人不会理解的术语,因为其他人需要能够读懂该注释,并且在快速浏览代码后,了解它的作用,但不一定要弄明白它是如何实现的。

第 5 段(可获 1.99 积分)

虽然我说通常情况下我不会再去写注释了,但是还是有需要写的时候的。如果有一段晦涩难懂的代码不能被分割成小的方法来说明它是做什么,并且也不能换一种方式来书写的话,注释可能就是唯一的解决办法了。尽管能够自解释的代码是理想的,但是书写注释总是比没有任何意义的代码要好多了。在任何情况下,都不应该允许一些人读一段代码时完全不知道写的是什么这种情况的发生。如果说需要什么东西的话,有的时候就可以是注释。

第 6 段(可获 1.4 积分)

另一个要写注释的情况是为了生成javadoc。当有人要在他们的代码使用它时,简短地描述一个函数的功能,这样会给你和他人提供便利。没有必要为每个方法都写javadoc,只需关注公共的方法,因为这些方法可以在代码库的其他部分中使用,并且为你编写的类编写javadoc以及说明何时使用它们也同样有用。要想进一步深入研究注释的用法和javadoc中一些有用的注解符号,请看https://www.tutorialspoint.com/java/java_documentation.htm

第 7 段(可获 1.53 积分)

如果你遵循这些准则,你的代码将更容易理解和明白——不仅为了你自己,也为了你的同事。你不会想当你回溯几个月前写的代码时,你的脑海里已经忘记了它的作用而对自己说“靠,这是什么鬼?” 吧!你的同事如果无需抓破头脑去理解你所写的代码,也就不会暴跳如雷,而如果你不想跟他们解释那些代码的话,那就不要给他们来问你的理由。

希望这篇文章可以帮助你理解该什么时候编写注释,并且避免在你以后的代码里加入大量杂乱无用的东西。

第 8 段(可获 1.6 积分)

文章评论

tony
刚翻译的时候还没有人翻译 :sweat:
班纳睿
是因为老大比较忙没有及时审核吧