原始文献 / 论坛帖 / Re: Source code documentation
Re: Source code documentation
Bitcointalk · 2010-07-16 15:37:00 UTC
我喜欢在对外 API 的库里这么做，但你大概能从代码看出来，我不喜欢给内部函数加这个。每个函数都加个大大的强制性注释头会把代码撑得很散，让你在创建一个小函数时犹豫——注释头比函数本身还大。维护起来也麻烦，函数一改，注释头也得跟着改。我喜欢保持代码紧凑，这样一屏能看到更多代码。
现在这个阶段再去加，写出来的也只是看函数就能看明白的东西。
我们现有的对外 API 在 rpc.cpp 里，用法文档都在帮助字符串里。
抱歉扫大家的兴。
英文原文
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.
The external API we have, in rpc.cpp, the usage documentation is in the help string.
Sorry to be a wet blanket.