註解主要的目的是讓其他人可以快速的理解程式碼，或是原始作者在後來修改自己的程式碼，不至於深陷混亂的程式碼泥沼當中。
但必須要注意註解過多過冗長不宜，因為註解本身不能取代程式碼，而程式碼才是主體。所以在註解上基本的原則是:
- 要說明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標準加上了
/*
這是多行註解, 來自C語言的註解方式
*/
/*也可以單行*/
//這是單行註解
/* // 多行註解裡可以有單行註解 */
//註解原來已有多行註解符號的區塊，使用預處理指令
#if 0
/* test function */
void test()
{
}
#endif
// or use 單行註解
///*
// test function
//*/
//void test()
//{
//}
//or use if(0){ } //使用語言本身的語法
if(0) //這會讓區塊內的程式碼不執行
{
/* test function */
void test()
{
}
}
將整段程式碼註解時一般可用多行註解的方式，
但是多行註解不可nested,
故若碰到段落內已有多行註解時則要
改用全部單行或是用preprocessor裡的#if 0的方式處理，
或是語言本身的 if(0)。
comment style
有時候為了使註解醒目，會用一些排列方式呈現
/** * * */ ///////////////////////////////////////////////// /// ///////////////////////////////////////////////// /*----------------------- | +----------------------- | *------------------------*/
一般來說，程式原始檔的註解會標記 檔案 作者 變更紀錄
function, class 等的註解
/*********************************************************************** * FILENAME : example.c * * DESCRIPTION : * This is an example. * * PUBLIC FUNCTIONS : * void test() * * AUTHOR : Enrico START DATE : 1 Jan 2000 * * CHANGE HISTORY : * * VERSION DATE DETAIL * 1.0 2000/01/01 fix .... * */
相關參考資料:
https://google.github.io/styleguide/cppguide.html#Comments
http://en.cppreference.com/w/c/comment
http://en.cppreference.com/w/cpp/comment
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
also
ISO/IEC 9899:1999 6.4.9
ISO/IEC 9899:1990 6.1.9