C++: Where to write the code documentation: in .cpp or in .hpp files?
Where is it customary to write the in-code documentation of classes and methods?
Do you write such doc-blocks above the corresponding class/method in the header (.hpp) file, or within the source (.cpp) file?
Is there a widely respected convention for such things? Do most C++ projects do it one way rather than the other?
Or should documentation be written on the two sides (ie in the .hpp and the .cpp files), maybe with one short description one one side and a longer one on the other side?
Most importantly, are there any practical considerations that makes it more convenient to write it one way rather than the other way ? (Eg the use of automatic documentation parsers and generators like Doxygen...)
Both:
Comment anything that's not obvious, and nothing that is (unless your documentation tool's too stupid to produce good documentation without).
Avoid putting implementation docs in the headers, as changing the header means makefile timestamp tests will trigger an unnecessary recompilation for client apps that include your header (at least in an enterprise or commercial library environment). For the same reason, aim to keep the header documentation stable and usable - good enough that you don't need to keep updating it as clients complain or ask for examples.
If you make a library, you typically distribute the compiled library and the header files. This makes it most useful to put documentation in the header files.
Again, both. As for the public documentation, it is nice to be in the .h with a format extractable with Doxygen, for example, as other commented. I like very much the Perl way of documenting things. The .pl (or .pm) file includes documentation in itself that can be extracted using a tool similar to what Doxygen does for C++ code. Also, Doxygen allows you to create several different pages, that allow you to include user manuals, etc., not just documenting the source code or API. I generally like the idea of a self-contained .h/.hpp file in the philosophy of literate programming.
链接地址: http://www.djcxy.com/p/14976.html上一篇: 是什么让Java编译器如此之快？