1. 让注释保持紧凑
1 //反面示例 2 // The int is the CategoryType. 3 // The first float in the inner pair is the 'score', 4 // the second is the 'weight'. 5 typedef hash_map<int, pair<float, float> > ScoreMap; 6 7 //正面示例 8 // CategoryType -> (score, weight) 9 typedef hash_map<int, pair<float, float> > ScoreMap;
2. 避免使用不明确的代词
1 // Insert the data into the cache, but check if it's too big first. 2 3 //1. 把it改成data 4 // Insert the data into the cache, but check if the data is too big first. 5 6 //2. 重组以使it更明确 7 // If the data is small enough, insert it into the cache.
3. 润色粗糙的句子
1 // Depending on whether we've already crawled this URL before, give it a different priority. 2 3 //更简单直接，且包含“优先级”相关的信息 4 // Give higher priority to URLs we've never crawled before.
4. 用精心挑选的例子进行说明
1 // Example: Strip("abba/a/ba", "ab") returns "/a/" 2 String Strip(String src, String chars) { ... }
5. ”具名参数函数“的注释
# Python # Call the function using named parameters Connect(timeout = 10, use_encryption = False) // C++ // Call the function with commented parameters Connect(/* timeout_ms = */ 10, /* use_encryption = */ false);
6. 采用信息量高的词
1 // This class acts as a caching layer to the database. 2 3 // Canonicalize the street address (remove extra spaces, "Avenue" -> "Ave.", etc.)