![]() ![]() Since global variables are evil but are sometimes necessary we should encourage developers to justify their existence, to apologize to future programmers and beg their forbearance for the indiscretion. It is very apparent in the generated documentation when developers only partially document these things. Similarly enumerations should have documentation both for the enumeration as a whole as well as individual items defined by it. For example, structures (and unions) require documentation describing both the structure itself as well as all of its members. Thus it is recommended that such items not be skipped from consideration merely because the meaning seems plain. ![]() In general, even though the purpose of an item may be obvious from its name, when rendered as documentation this implicit meaning is not always forthcoming. However static and inline functions in header files are much more widely visible and should be documented. In general, static and inline functions within modules are not visible outside that module and thus adding a documentation block may be of limited value (with exceptions, such as when used for function pointers for consumption elsewhere) though this does not excuse a developer from writing useful comments.
0 Comments
Leave a Reply. |