SN-1269 已核对来源,附原文与上下文。
对外 API 的库代码里我喜欢注释头,但从代码你应该看得出来,内部函数我不是这种风格的拥趸。给每个函数都加一个必写的大注释头,会把代码撑开,让你在写一个小函数时犹豫不决——注释头比函数本身还大。它们对维护也是种麻烦,函数一改,注释头就得跟着改两遍。我喜欢把代码写紧凑些,好让一屏能看到更多代码。
I like that in libraries for the external API's, but you can probably tell from the code that I'm not a fan of it for interior functions. Big obligatory comment headers for each function space out the code and make you hesitate about creating a small little function where the comment header would be bigger than the function. They're some trouble for maintenance, as changes to the function then require duplicate changes in the comment header. I like to keep code compact so you can see more code on the screen at once.
事到如今再补的话,写出来的只会是看函数一眼就能明白的东西。
To add them now at this point, what would be written would just be what's obvious from looking at the function.
我们现有的对外 API 在 rpc.cpp,用法文档在帮助字符串里。
The external API we have, in rpc.cpp, the usage documentation is in the help string.
扫兴了,抱歉。
Sorry to be a wet blanket.