国产精品国产毛片,成人国产经典视频,中文字字幕在线中文,亚洲精品一二三区,仓井空一区二区,仓井空无码一区,大秀蕉丝袜国产,日本特黄一级

整理/來源：strongerHuang

轉(zhuǎn)載：codesheep

如果領(lǐng)導(dǎo)給你一個(gè)項(xiàng)目的源碼讓你閱讀，并理解重構(gòu)代碼，但里面一句注釋都沒有，我想這肯定是之前同事“刪庫跑路”了。

看一份源碼什么很重要？除了各種代碼規(guī)范之外，還有一個(gè)比較重要的就是注釋。

注釋雖然寫起來很痛苦, 但對保證代碼可讀性至關(guān)重要，下面我們就以C/C++代碼規(guī)范注釋為例，將描述如何注釋以及有哪些講究。

注釋風(fēng)格

1. 總述

一般使用?//?或?/*?*/，只要統(tǒng)一就好。

2. 說明

//?或?/*?*/?都可以，但團(tuán)隊(duì)要在如何注釋及注釋風(fēng)格上確保統(tǒng)一。

文件注釋

1. 總述

在每一個(gè)文件開頭加入版權(quán)、作者、時(shí)間等描述。

文件注釋描述了該文件的內(nèi)容，如果一個(gè)文件只聲明，或?qū)崿F(xiàn)，或測試了一個(gè)對象，并且這個(gè)對象已經(jīng)在它的聲明處進(jìn)行了詳細(xì)的注釋，那么就沒必要再加上文件注釋，除此之外的其他文件都需要文件注釋。

2. 說明

法律公告和作者信息：

每個(gè)文件都應(yīng)該包含許可證引用。也要為項(xiàng)目選擇合適的許可證版本(比如, Apache 2.0, BSD, LGPL, GPL)。

3. 文件內(nèi)容

如果一個(gè)?.h?文件聲明了多個(gè)概念, 則文件注釋應(yīng)當(dāng)對文件的內(nèi)容做一個(gè)大致的說明, 同時(shí)說明各概念之間的聯(lián)系。一個(gè)一到兩行的文件注釋就足夠了, 對于每個(gè)概念的詳細(xì)文檔應(yīng)當(dāng)放在各個(gè)概念中, 而不是文件注釋中。

不要在?.h?和?.cc?之間復(fù)制注釋, 這樣的注釋偏離了注釋的實(shí)際意義。

最后再舉個(gè)最簡單的實(shí)際例子：

/**************************************************************************????Copyright? Copyright?2020?Google?Inc.*????File?Name: 文件名*????Description: 描述**????Version:?V1.0*????Author: Your_Name*????Create?Time:?2020-01-01**************************************************************************/

函數(shù)注釋

1. 總述

函數(shù)聲明處的注釋描述函數(shù)功能; 定義處的注釋描述函數(shù)實(shí)現(xiàn)。

2. 說明

函數(shù)聲明：

基本上每個(gè)函數(shù)聲明處前都應(yīng)當(dāng)加上注釋, 描述函數(shù)的功能和用途。只有在函數(shù)的功能簡單而明顯時(shí)才能省略這些注釋(例如, 簡單的取值和設(shè)值函數(shù))。

比如：

/**************************************************************************    函 數(shù) 名：函數(shù)名*    函數(shù)功能：功能描述*    輸入?yún)?shù)：void*    輸出參數(shù)：void*    返 回 值:  void**    作    者：Your_Name*????創(chuàng)建時(shí)間：2020-01-01*    其他說明：無*    修改信息：無*************************************************************************/

函數(shù)定義：

如果函數(shù)的實(shí)現(xiàn)過程中用到了很巧妙的方式, 那么在函數(shù)定義處應(yīng)當(dāng)加上解釋性的注釋。比如, 你所使用的編程技巧, 實(shí)現(xiàn)的大致步驟, 或解釋如此實(shí)現(xiàn)的理由。舉個(gè)例子, 你可以說明為什么函數(shù)的前半部分要加鎖而后半部分不需要。

不要?從?.h?文件或其他地方的函數(shù)聲明處直接復(fù)制注釋. 簡要重述函數(shù)功能是可以的, 但注釋重點(diǎn)要放在如何實(shí)現(xiàn)上。

變量注釋

1. 總述

通常變量名本身足以很好說明變量用途，某些情況下, 也需要額外的注釋說明。

2. 說明

根據(jù)不同場景、不同修飾符，變量可以分為很多種類，總的來說變量分為全局變量、局部變量。

一般來說局部變量僅限于局部范圍，其含義相對簡單容易理解，只需要簡單注釋即可。

全局變量一般作用于多個(gè)文件，或者整個(gè)工程，因此，其含義相對更復(fù)雜，所以在注釋的時(shí)候，最好描述清楚其具體含義，就是盡量全面描述。

（提示：全局變量盡量少用）

拼寫注釋

1. 總述

可能一個(gè)變量、一個(gè)函數(shù)包含的意思非常復(fù)雜，需要多個(gè)單詞拼寫而成，此時(shí)對拼寫內(nèi)容就需要詳細(xì)注釋。

2. 說明

注釋的通常寫法是包含正確大小寫和結(jié)尾句號的完整敘述性語句。大多數(shù)情況下, 完整的句子比句子片段可讀性更高。短一點(diǎn)的注釋, 比如代碼行尾注釋, 可以隨意點(diǎn), 但依然要注意風(fēng)格的一致性。

同時(shí)，注釋中的拼寫、逗號也很重要。雖然被別人指出該用分號時(shí)卻用了逗號多少有些尷尬, 但清晰易讀的代碼還是很重要的。正確的標(biāo)點(diǎn), 拼寫和語法對此會有很大幫助

TODO 注釋

1. 總述

對那些臨時(shí)的, 短期的解決方案, 或已經(jīng)夠好但仍不完美的代碼使用?TODO?注釋。

TODO?注釋要使用全大寫的字符串?TODO, 在隨后的圓括號里寫上你的名字, 郵件地址, bug ID, 或其它身份標(biāo)識和與這一?TODO?相關(guān)的 issue。主要目的是讓添加注釋的人 (也是可以請求提供更多細(xì)節(jié)的人) 可根據(jù)規(guī)范的?TODO?格式進(jìn)行查找。添加?TODO?注釋并不一定意味著你要自己來修正, 因此當(dāng)你加上帶有姓名的?TODO?時(shí), 一般都是寫上自己的名字。

結(jié) 語

注釋固然很重要, 但最好的代碼應(yīng)當(dāng)本身就是文檔，有意義的類型名和變量名, 要遠(yuǎn)勝過要用注釋解釋的含糊不清的名字。

你寫的注釋是給代碼閱讀者看的, 也就是下一個(gè)需要理解你代碼的人. 所以慷慨些吧, 下一個(gè)讀者可能就是你！

程序員GitHub，現(xiàn)已正式上線！

接下來我們將會在該公眾號上，專注為大家分享GitHub上有趣的開源庫包括Python,Java,Go，前端開發(fā)等優(yōu)質(zhì)的學(xué)習(xí)資源和技術(shù)，分享一些程序員圈的新鮮趣事。

推薦閱讀：

這個(gè)GitHub 1400星的Git魔法書火了，斯坦福校友出品丨有中文版
賊 TM 好用的 Java 工具類庫
超全Python IDE武器庫大總結(jié)，優(yōu)缺點(diǎn)一目了然！
秋招來襲！GitHub28.5顆星！這個(gè)匯聚阿里，騰訊，百度，美團(tuán)，頭條的面試題庫必須安利！
收獲10400顆星！這個(gè)Python庫有點(diǎn)黑科技，竟然可以偽造很多'假'的數(shù)據(jù)！
牛掰了！這個(gè)Python庫有點(diǎn)逆天了，竟然能把圖片，視頻無損清晰放大！

點(diǎn)這里，獲取一大波福利

給代碼寫注釋時(shí)有哪些講究？

點(diǎn)這里，獲取一大波福利

給代碼寫注釋時(shí)有哪些講究？

點(diǎn)這里，獲取一大波福利