Daily Archives: May 28, 2017

註解主要的目的是讓其他人可以快速的理解程式碼，或是原始作者在後來修改自己的程式碼，不至於深陷混亂的程式碼泥沼當中。但必須要注意註解過多過冗長不宜，因為註解本身不能取代程式碼，而程式碼才是主體。所以在註解上基本的原則是: 要說明function/class的目的，在function內部不易閱讀的地方註記使用的演算法或是方法的目的(rationale)，讓閱讀者可以抓住開發者當時的思路。 workaround的部分也必須註記，因為通常workaround不是在原來的正常思路當中，如果不加以註記，有很大的機會在後來會完全摸不著頭緒 另外是如果整合了文件產生工具或是IDE整合，為了要讓工具提取重要的metadata，註解的格式就會有所規範，可以參考https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html,XML Documentation (Visual C++) 在C/C++裡註解分兩種: 單行註解(single-line comments, C style) 與 多行註解(multi-line comments, C++ style)C89不支援單行註解，但C99標準加上了 將整段程式碼註解時一般可用多行註解的方式，但是多行註解不可nested,故若碰到段落內已有多行註解時則要改用全部單行或是用preprocessor裡的#if 0的方式處理，或是語言本身的 if(0)。 comment style有時候為了使註解醒目，會用一些排列方式呈現 一般來說，程式原始檔的註解會標記 檔案 作者 變更紀錄function, class 等的註解 相關參考資料:https://google.github.io/styleguide/cppguide.html#Commentshttp://en.cppreference.com/w/c/commenthttp://en.cppreference.com/w/cpp/commenthttp://www.oracle.com/technetwork/java/javase/documentation/index-137868.htmlalsoISO/IEC 9899:1999 6.4.9ISO/IEC 9899:1990 6.1.9