C语言coding时尽量不要写注释

coding时尽量不要写注释

在学堂里学习时,老师对注释的要求较严格。

公写代码的当儿不写注释,过一段时间你自己还看不知底了,何况人家?

齐一致句还属于常规观点。某个老师竟这样说:

C语言,注释量应该跟代码量优秀。

就,我是心中敬仰的。但是,工作后发现,实际工程领域中,并没那么多注释。
与此同时,渐渐发现,大部情下不待、也不应该注释

鉴于工作被因为Java为主——这确实是一个伤心的故事——以下代码以Java为条例。

1. 左的诠释不如没有

注写出来,就是给人拘禁的。假如注释是错的,就会合误导代码阅读者。

/**
 * I am a boy, I like girls.
 *
 * @param someone is a Person who is welcome or not.
 *
 * @return true if someone is a Person you like.
 */
private boolean isWelcome(Person someone) {
  return someone.isBoy();
}

随下边这段,代码是只同性恋写的,注释的则是异性恋;或者,当他形容注释的时光觉得自己性取向那一个正规,写代码的上心里忽然涌上一阵明悟……

顿时类似注释在实际上工作被碰着很多。在保障代码、或者是以往日的根基及出代码的长河遭到,往往是进行增量修改。某些时候,Method内的贯彻就变更了,而代码注释未移,就爱出现互相不等同,甚至意义了相反。

改代码时,一定如若先行改相关注释。这就是带了保安资金的增高。

题材是:增添的维护资产和误导几引领,是否会被诠释带来的收入所抵?

2. 从未额外语意的注释不若不写

声明不仅使表明,还非得使有非凡语意,或者另行简单地表达了同代码实际效果相同之意。

public class Person {
    /** The name of the Person. */
    private String name;
    /** The phone number of the Person. */
    private String phoneNumber;
}

方那段,那样的笺注,有什么意思?

  • name匪就name吗?难道还欲再行说一样所有,或者译成粤语?
  • phoneNumber莫就是电话号码吗?难道要当诠释里拆起来,代码的阅读者才会看了然?

眼看类为诠释而注释的注脚,除了碍眼,并凭意义。而且,还易于出现第1类题目。

遵,将来人类还休想登记、购买电话号码了,直接用身份证号作为联系形式。下边的代码需要拿phoneNumber改为id,修改者会不会合记得改注释?

他心中一定生一万头草泥马以奔向:还不苟删掉!

3. 必不可少之笺注是代码的败北

实在,看代码的人口犹是码农……呃,我是因,看代码的口依然能看代码的食指。一般不碰面设有尚未注释就看无知晓的代码。

阐明只然则是加速通晓代码的经过。

以,看了诠释,不意味就非需看代码。因为起或有第1看似题材。

/**
 * @return true if this is a girl and she is beautiful.
 */
public boolean isGood() {
    int value = this.getValue();

    // If the 1st bit of value is 0, means this is a girl.
    // If the 2nd bit of value is 0, means this person is beautiful.
    if ((value & 0x01) == 0 && (value & 0x02) == 0) {
        return true;
    } else {
        return false;
    }
}

上述代码中,Method的注释已经勾勒得甚懂了,isGood()凡是圈之人是休是单淑女。
旋即段注释的确加速了晓,因为isGood()并无是大直观。什么样的好才是好?

唯独,为何不把Method命名为isBeautifulGirl()?表明了一如既往意义之而,也非用阅读者跳反到定义地点来拘禁。

下,在贯彻着之立即段注释的确加速了明,不然这一个位操作而看颇深切(视脑年龄要肯定)。

但是,特么哪位准而当Java里用位操作?!

任由您这int里怀了略微位之信,为啥非克拆分成四个价?
如拆分成基本上只价,每个值都给予适当的命名,配以适量的Method,为啥还亟需注释?

比如以下代码,需要注释也?

public boolean isBeautifulGirl() {
    return isGirl() && isBeautiful();
}

当你吃自己的代码逼迫,以致要描写注释从前,你应该问自己:是休是随即段代码写得最为不佳了?要么再变更改?

4. 相对并非写粤语注释

则代码往往仍旧以英文为底蕴之,代码旁边放以大段的英文注释也确令人抓狂。

不过比英文更使人抓狂的是乱码

双重叫人围捕狂的是,怎么变换都是乱码乱码

/**
 * ��Ҳ��֪�����Ǹ�ʲô��
 */
public void doSomething() {
}

孰能管此乱码转回来,看看我注释里写了呀?

另外,是未是发平等栽删掉的兴奋?

吓之代码本身便是注释

Person person = I.meet();
if (person instanceof Girl) {
    Girl she = (Girl) person;
    if (she.isBeautiful()) {
        if (she.isKind()) {
            I.marry(she);
        } else if (she.isBitch()) {
            I.fuck(she);
        } else {
            I.play(she);
        }
    } else {
        I.doNothing();
    }
} else {
    I.stayLonely();
}

上述代码,即使if至极了几许,可是不需要注释也截然可读。哪怕从自然语言的语法角度看呢问题多,不过,代码的逻辑就是以这边,比其他自然语言更确切地讲述了程序的骨子里运行状况。

There are a thousand Hamlets in a thousand people’s eyes.

一千独读者就闹一千个哈姆雷特(哈姆雷特(Hamlet))。

——莎士比亚(Shakespeare)(莎士比亚(Shakespeare))

倘使你强行要拿编程语言编译成自然语言,你能够确定你表达了您想发挥的,你确定你想表明的即是程序实际运作的?

若确定无发前的季接近题材?
诠释,需如若达了与代码相同涵义(第1看似题目)、而还要不可知是一律语意(第2近似题材)、在代码相比较复杂或难读(第3近乎题目)、并且不克为此ASCII以外的字符的情景下,写在代码旁边说代码的物。

(其实一词话就是会输大多数神州程序员:你英文写得较代码好?)

从而,如故吃合尽在代码中吧!

Code is poetry.

log即注释

以其实的工作遭到,你得无写注释,但只好写log。

注脚是描摹于代码阅读者看之,并无出席编译。仅是和代码中,编译后的软件里并无存在。

设log是为着调节、后续debug的便民而添加的。突出的log,能够让我们在log文件被,看清软件之实在运作状态。

以翻阅代码时,

局部不等

诠释,这种语法的在还是出必不可少之,只是大部分程序员其实从用无交、或因而了未来应该这去。

C语言,API

如,最该写注释的,是供于外人——通常是另一个team、甚至店——用的public接口,也不怕是所谓API。
Java的API文档,往往是透过javadoc生成的。这样的好处是,开发代码的同时支付文档,保持一致性。

只是普通不待十分多维护,因为公开的API是休可以随随便便改动的,最酷之改动往往是加一个@deprecated
于是,其实API文档分开单独写吗不是未得以。

其中用的public,代码实现仍是可以够给看见,文档也即使好不了。
实在是从未文档看不懂代码,不会面咨询吗?

干“脏活儿”

奇迹,需要发挥的逻辑本身便这么些复杂。典型如以普遍的即使是多线程,往往难以了然以及跟。

众多时节,某些语言,尤其是C语言,干的仍然把“脏活儿”。为了确保性能,往往要怎么飞快怎么来。一些递归函数里,多定义一个变量,都能够影响到空间复杂度。

涉及脏活儿,想不污染,不容易。

而是,如若真的相比较复杂,仍旧独立的文档,或者UML图于实用。

汇编就重不用提了。这一个时期,你会写,你免克要旁人会看。

TODO和FIXME

及时俩,说是注释,其实应当算标记。

  • TODO: 表示尚生未形成的劳作,往往是开进程遭到行使。

  • FIXME:
    表示此有bug,或者可能有bug,但小无法缓解。这往往是发表时用。

然,程序员的一样挺恨事就是:在别人release过来的代码里,发现及时哥们儿!

临时去丢一部分代码

调节时为此注释来disable一些代码,以免删除了还得更写或贴。

不过,调试好后,不要的代码一定假诺删掉!

结论

  • 尽快去注释去!
  • 毫不主动写API以外的诠释!
  • 代码要写得雅观一点。
  • 后的劳作面临,何人被写注释就有理有据地喷回去!
  • 而因看了本文而生的别实际变化,如若当干活及习中带来了另外负面结果,请自行承担。