C語(yǔ)言如何注釋以及在哪兒注釋
如果領(lǐng)導(dǎo)給你一個(gè)項(xiàng)目的源碼讓你閱讀，并理解重構(gòu)代碼，但里面一句注釋都沒(méi)有，我想這肯定是之前同事“刪庫(kù)跑路”了。 看一份源碼什么很重要？除了各種代碼規(guī)范之外，還有一個(gè)比較重要的就是注釋。 注釋雖然寫起來(lái)很痛苦, 但對(duì)保證代碼可讀性至關(guān)重要，下面的將描述如何注釋以及在哪兒注釋。
注釋風(fēng)格
1.總述
一般使用//或/**/，只要統(tǒng)一就好。
2.說(shuō)明
//或/**/都可以，但//更常用，要在如何注釋及注釋風(fēng)格上確保統(tǒng)一。
文件注釋
1.總述在每一個(gè)文件開(kāi)頭加入版權(quán)、作者、時(shí)間等描述。 文件注釋描述了該文件的內(nèi)容，如果一個(gè)文件只聲明，或?qū)崿F(xiàn)，或測(cè)試了一個(gè)對(duì)象，并且這個(gè)對(duì)象已經(jīng)在它的聲明處進(jìn)行了詳細(xì)的注釋，那么就沒(méi)必要再加上文件注釋，除此之外的其他文件都需要文件注釋。 2.說(shuō)明法律公告和作者信息：每個(gè)文件都應(yīng)該包含許可證引用. 為項(xiàng)目選擇合適的許可證版本(比如, Apache 2.0, BSD, LGPL, GPL)。 如果你對(duì)原始作者的文件做了重大修改，請(qǐng)考慮刪除原作者信息。 3.文件內(nèi)容
如果一個(gè).h文件聲明了多個(gè)概念, 則文件注釋應(yīng)當(dāng)對(duì)文件的內(nèi)容做一個(gè)大致的說(shuō)明, 同時(shí)說(shuō)明各概念之間的聯(lián)系. 一個(gè)一到兩行的文件注釋就足夠了, 對(duì)于每個(gè)概念的詳細(xì)文檔應(yīng)當(dāng)放在各個(gè)概念中, 而不是文件注釋中。
不要在.h和.cc之間復(fù)制注釋, 這樣的注釋偏離了注釋的實(shí)際意義。
函數(shù)注釋
1.總述函數(shù)聲明處的注釋描述函數(shù)功能; 定義處的注釋描述函數(shù)實(shí)現(xiàn)。 2.說(shuō)明函數(shù)聲明：基本上每個(gè)函數(shù)聲明處前都應(yīng)當(dāng)加上注釋, 描述函數(shù)的功能和用途. 只有在函數(shù)的功能簡(jiǎn)單而明顯時(shí)才能省略這些注釋(例如, 簡(jiǎn)單的取值和設(shè)值函數(shù))。 比如：FreeRTOS創(chuàng)建任務(wù)函數(shù)申明：
不要從.h文件或其他地方的函數(shù)聲明處直接復(fù)制注釋. 簡(jiǎn)要重述函數(shù)功能是可以的, 但注釋重點(diǎn)要放在如何實(shí)現(xiàn)上。
變量注釋
1.總述通常變量名本身足以很好說(shuō)明變量用途， 某些情況下, 也需要額外的注釋說(shuō)明。2.說(shuō)明根據(jù)不同場(chǎng)景、不同修飾符，變量可以分為很多種類，總的來(lái)說(shuō)變量分為全局變量、局部變量。 一般來(lái)說(shuō)局部變量?jī)H限于局部范圍，其含義相對(duì)簡(jiǎn)單容易理解，只需要簡(jiǎn)單注釋即可。 全局變量一般作用于多個(gè)文件，或者整個(gè)工程，因此，其含義相對(duì)更復(fù)雜，所以在注釋的時(shí)候，最好描述清楚其具體含義，就是盡量全面描述。（提示：全局變量盡量少用）
拼音注釋
1.總述可能一個(gè)變量、一個(gè)函數(shù)包含的意思非常復(fù)雜，需要多個(gè)單詞拼寫而成，此時(shí)對(duì)拼寫內(nèi)容就需要詳細(xì)注釋。2.說(shuō)明注釋的通常寫法是包含正確大小寫和結(jié)尾句號(hào)的完整敘述性語(yǔ)句. 大多數(shù)情況下, 完整的句子比句子片段可讀性更高. 短一點(diǎn)的注釋, 比如代碼行尾注釋, 可以隨意點(diǎn), 但依然要注意風(fēng)格的一致性。 同時(shí)，注釋中的拼寫、逗號(hào)也很重要。雖然被別人指出該用分號(hào)時(shí)卻用了逗號(hào)多少有些尷尬, 但清晰易讀的代碼還是很重要的. 正確的標(biāo)點(diǎn), 拼寫和語(yǔ)法對(duì)此會(huì)有很大幫助
TODO 注釋
1.總述對(duì)那些臨時(shí)的, 短期的解決方案, 或已經(jīng)夠好但仍不完美的代碼使用TODO注釋。TODO注釋要使用全大寫的字符串TODO, 在隨后的圓括號(hào)里寫上你的名字, 郵件地址, bug ID, 或其它身份標(biāo)識(shí)和與這一TODO相關(guān)的 issue. 主要目的是讓添加注釋的人 (也是可以請(qǐng)求提供更多細(xì)節(jié)的人) 可根據(jù)規(guī)范的TODO格式進(jìn)行查找. 添加TODO注釋并不意味著你要自己來(lái)修正, 因此當(dāng)你加上帶有姓名的TODO時(shí), 一般都是寫上自己的名字。最后
注釋固然很重要, 但最好的代碼應(yīng)當(dāng)本身就是文檔，有意義的類型名和變量名, 要遠(yuǎn)勝過(guò)要用注釋解釋的含糊不清的名字。
你寫的注釋是給代碼閱讀者看的, 也就是下一個(gè)需要理解你代碼的人. 所以慷慨些吧, 下一個(gè)讀者可能就是你！
審核編輯 ：李倩
聲明：本文內(nèi)容及配圖由入駐作者撰寫或者入駐合作網(wǎng)站授權(quán)轉(zhuǎn)載。文章觀點(diǎn)僅代表作者本人，不代表電子發(fā)燒友網(wǎng)立場(chǎng)。文章及其配圖僅供工程師學(xué)習(xí)之用，如有內(nèi)容侵權(quán)或者其他違規(guī)問(wèn)題，請(qǐng)聯(lián)系本站處理。
舉報(bào)投訴
-
C語(yǔ)言
+關(guān)注
關(guān)注
180文章
7618瀏覽量
138711 -
代碼
+關(guān)注
關(guān)注
30文章
4858瀏覽量
69553
原文標(biāo)題：C語(yǔ)言的注釋要注意幾點(diǎn)
文章出處：【微信號(hào)：strongerHuang，微信公眾號(hào)：strongerHuang】歡迎添加關(guān)注！文章轉(zhuǎn)載請(qǐng)注明出處。
發(fā)布評(píng)論請(qǐng)先 登錄
相關(guān)推薦
STM32CUBEide有沒(méi)有像KEIL一樣可以自己指定函數(shù)注釋模板的方法？
最近從keil轉(zhuǎn)到CUBEIDE編程了，現(xiàn)在非常不舒服的一點(diǎn)是函數(shù)注釋方面。STM32CUBEide有沒(méi)有像KEIL一樣可以自己指定函數(shù)注釋模板的方法，可以注釋函數(shù)形參啊、函數(shù)返回值說(shuō)明的方法
發(fā)表于 03-11 08:06
DLP650LNIR芯片安裝部分的三維機(jī)械模型在哪兒下載？
請(qǐng)問(wèn)，想設(shè)計(jì)DLP650LNIR部分的板卡，DLP650LNIR芯片安裝部分有一些結(jié)構(gòu)件，在哪能下載到這些三維機(jī)械模型？
發(fā)表于 02-24 07:25
C語(yǔ)言關(guān)鍵字分別發(fā)生在哪個(gè)階段
以下C語(yǔ)言關(guān)鍵字，分別發(fā)生在哪個(gè)階段？ 第一個(gè)，define。 首先得糾正一下，define 并不是C語(yǔ)言里面的關(guān)鍵字，即使加了井號(hào)，也不是
PCM2707為什么無(wú)法被電腦識(shí)別？
現(xiàn)在只焊接了最基礎(chǔ)的部分,其它如控制跟I2S接口都還沒(méi)連接元件,相當(dāng)于空接,,現(xiàn)在無(wú)法被電腦識(shí)別,系統(tǒng)WI8-64BIT,我購(gòu)買的PCM2704的板可以被電腦正常識(shí)別,請(qǐng)問(wèn)下,問(wèn)題出在哪兒
發(fā)表于 11-06 06:25
請(qǐng)問(wèn)有沒(méi)有單片機(jī)通過(guò)I2C配置AIC3204的相關(guān)例程，或者在哪兒可以找到？
請(qǐng)問(wèn)有沒(méi)有單片機(jī)通過(guò)I2C配置AIC3204的相關(guān)例程，或者在哪兒可以找到？例如設(shè)置AIC3204的ADC等
發(fā)表于 11-01 07:36
C語(yǔ)言與Java語(yǔ)言的對(duì)比
C語(yǔ)言和Java語(yǔ)言都是當(dāng)前編程領(lǐng)域中的重要成員，它們各自具有獨(dú)特的優(yōu)勢(shì)和特點(diǎn)，適用于不同的應(yīng)用場(chǎng)景。以下將從語(yǔ)法特性、內(nèi)存管理、跨平臺(tái)性、性能、應(yīng)用領(lǐng)域等多個(gè)方面對(duì)C
新能源機(jī)車電傳動(dòng)系統(tǒng)“新”在哪兒
中國(guó)中車面向全球首次發(fā)布系列化新能源機(jī)車，7款代表車型集中亮相。中車永濟(jì)電機(jī)公司為系列化新能源機(jī)車研制開(kāi)發(fā)了電傳動(dòng)系統(tǒng)解決方案，包括牽引輔助變流系統(tǒng)、牽引電機(jī)、網(wǎng)絡(luò)控制系統(tǒng)等核心部件。
TLV2252A運(yùn)放產(chǎn)生了低頻振蕩是哪里出了問(wèn)題？
如圖所示，本人用作一個(gè)紅外傳感器的驅(qū)動(dòng)，但是運(yùn)放輸出莫名的振蕩了，請(qǐng)幫忙看看原因是什么了？ 輸出振蕩信號(hào)為參考電壓（225mv）到軌電壓（3V3）的一個(gè)低頻振蕩（2.46HZ）。
請(qǐng)大拿們幫忙看看問(wèn)題出在哪兒了？
發(fā)表于 07-31 06:52
esp8266向http server發(fā)送post請(qǐng)求，發(fā)送一段時(shí)間之后會(huì)返回ESPCONN_MEM，為什么？
callback，然后再發(fā)下一包，我不知道tcp_pcb是在哪兒close和刪除的，我嘗試在disconnect callback和reconnect callback中調(diào)用espconn_delete或
發(fā)表于 07-10 08:13
ESP-ADF例程編譯過(guò)程出錯(cuò)，提示找不到“esp_afe_sr_iface.h”文件，為什么？
ESP-ADF例程編譯過(guò)程出錯(cuò)，提示找不到“esp_afe_sr_iface.h”文件，在github和gitee倉(cāng)庫(kù)上找遍了也沒(méi)有這個(gè)文件，請(qǐng)問(wèn)有大神知道在哪兒有嗎？
發(fā)表于 06-17 08:03
PLC編程語(yǔ)言和C語(yǔ)言的區(qū)別
在工業(yè)自動(dòng)化和計(jì)算機(jī)編程領(lǐng)域中，PLC（可編程邏輯控制器）編程語(yǔ)言和C語(yǔ)言各自扮演著重要的角色。盡管兩者都是編程語(yǔ)言，但它們?cè)诙鄠€(gè)方面存在顯著的區(qū)別。本文將從多個(gè)維度深入探討PLC編程
在哪兒可以修改DAC口的輸出變量？
大家好，就是workbench生成程序的時(shí)候，會(huì)在DAC那里選擇通道的輸出信息。然后脫離Workbench想在程序里直接修改的時(shí)候在dac_ui.c里往下找的時(shí)候，找到了在user_interface.h里邊有很多這個(gè)定義，但就是沒(méi)明白在哪兒可以修改DAC口的輸出變量。所
發(fā)表于 04-02 06:45
labview時(shí)頻域分析
各位，問(wèn)一下我的這個(gè)幅值頻譜圖的幅值為什么和時(shí)域不匹配，請(qǐng)問(wèn)問(wèn)題出在哪兒？感謝！！！
發(fā)表于 03-30 15:56
NUCLEO-G474RE開(kāi)發(fā)板的例程在哪兒下載？如和用usb和pc串口通信？
NUCLEO-G474RE這個(gè)開(kāi)發(fā)板的例程在哪兒下載啊，不知道如和用他的usb和pc串口通信
發(fā)表于 03-18 08:22
工商網(wǎng)監(jiān)
評(píng)論