C++核心準(zhǔn)則?：注釋風(fēng)格

NL.1: Don't say in comments what can be clearly stated in code

NL.1：請不要在注釋中說明代碼可以清楚表達(dá)的內(nèi)容

Reason（原因）

Compilers do not read comments. Comments are less precise than code. Comments are not updated as consistently as code.

編譯器不閱讀注釋。注釋不如代碼精確。注釋不會一直隨代碼一起更新。

Example, bad（反面示例）

auto x = m * v1 + vv;   // multiply m with v1 and add the result to vv

Enforcement（實(shí)施建議）

Build an AI program that interprets colloquial English text and see if what is said could be better expressed in C++.

建立一個可以解釋口語英語文本的AI程序，看看是否可以用C ++更好地表達(dá)。

NL.2: State intent in comments

NL.2:?在注釋中說明意圖

Reason（原因）

Code says what is done, not what is supposed to be done. Often intent can be stated more clearly and concisely than the implementation.

代碼說明做了什么，而不會說明應(yīng)該做什么。通常意圖得表達(dá)可以比實(shí)現(xiàn)更清楚，更簡明。

Example（示例）

void stable_sort(Sortable& c)
    // sort c in the order determined by <, keep equal elements (as defined by ==) in
    // their original relative order
{
    // ... quite a few lines of non-trivial code ...
}

Note（注意）

If the comment and the code disagree, both are likely to be wrong.

如果注釋和代碼相矛盾，則兩者可能都是錯誤的。

NL.3: Keep comments crisp

NL.3：保持注釋清晰

Reason（原因）

Verbosity slows down understanding and makes the code harder to read by spreading it around in the source file.

過于詳細(xì)的注釋減慢代碼的理解速度，這種注釋在源文件中四處傳播會使代碼難以閱讀。

Note（注意）

Use intelligible English. I might be fluent in Danish, but most programmers are not; the maintainers of my code might not be. Avoid SMS lingo and watch your grammar, punctuation, and capitalization. Aim for professionalism, not "cool."

使用可理解的英語。我可能會說流利的丹麥語，但大多數(shù)程序員不是。我的代碼的維護(hù)者可能不是。避免使用SMS術(shù)語，并注意語法，標(biāo)點(diǎn)和大寫字母。追求專業(yè)，而不是“酷”。

Enforcement（實(shí)施建議）

not possible.

原文鏈接

https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#nl-naming-and-layout-rules

新書介紹

《實(shí)戰(zhàn)Python設(shè)計模式》是作者最近出版的新書，拜托多多關(guān)注！

本書利用Python 的標(biāo)準(zhǔn)GUI 工具包tkinter，通過可執(zhí)行的示例對23 個設(shè)計模式逐個進(jìn)行說明。這樣一方面可以使讀者了解真實(shí)的軟件開發(fā)工作中每個設(shè)計模式的運(yùn)用場景和想要解決的問題；另一方面通過對這些問題的解決過程進(jìn)行說明，讓讀者明白在編寫代碼時如何判斷使用設(shè)計模式的利弊，并合理運(yùn)用設(shè)計模式。

對設(shè)計模式感興趣而且希望隨學(xué)隨用的讀者通過本書可以快速跨越從理解到運(yùn)用的門檻；希望學(xué)習(xí)Python GUI 編程的讀者可以將本書中的示例作為設(shè)計和開發(fā)的參考；使用Python 語言進(jìn)行圖像分析、數(shù)據(jù)處理工作的讀者可以直接以本書中的示例為基礎(chǔ)，迅速構(gòu)建自己的系統(tǒng)架構(gòu)。

---

覺得本文有幫助？請分享給更多人。

關(guān)注微信公眾號【面向?qū)ο笏伎肌枯p松學(xué)習(xí)每一天！

面向?qū)ο箝_發(fā)，面向?qū)ο笏伎迹?/span>