| Chris Vine <chris@cvine--nospam--.freeserve.co.uk>: Oct 03 04:25PM +0100 On 2 Oct 2015 21:40:52 GMT > > written as a separate document such as cppreference). > I don't -- like Vir I read the header file to see the API. And it > seems those C++ Core Guidelines aim to support us, which is nice. I do not often seem to find myself agreeing with Stefan, but I am pleased that on this occasion I do. IMO the correct place to provide documentation for a library is in the library documentation, which can be generated from the header file using doxygen or other third-party tools. If the library author cannot be bothered to document the public interfaces of the library, then I would not want to use it. Enforcing an arbitrary rule about the ordering of class members in the class definition as a substitute for inadequate or non-existent documentation seems crazy to me. Nonetheless, I thought I was pretty old school in preferring to provide member data declarations (usually private) before member function declarations (usually public) in class definitions. Particularly when looking at an inline method, including all methods defined within the body of a template class definition, I like to look at the code in an upwards direction to find the object data that the method is operating on and not scrabble around for some mention of it later in the header file. It is interesting that it appears I am not alone in that preference. I fully realize that the look-up rules for struct/class definitions mean that (unlike with most other uses of undeclared variables in C++) there is no language impediment to having an inline method operate on a data member before that data member has been declared. However, I do not like the practice. Of course, for non-library code, there may not be a need for separate documentation. But for these, the people interested in the code are only the original author(s) and any subsequent maintainer(s). As mentioned, for these I prefer the declare-before-use approach. Chris |
| Jorgen Grahn <grahn+nntp@snipabacken.se>: Oct 03 09:27PM On Sat, 2015-10-03, Chris Vine wrote: > I do not often seem to find myself agreeing with Stefan, but I am > pleased that on this occasion I do. > IMO the correct place to provide documentation for a library Oh. I was talking about non-library code only. I was going to state that above, but changed my mind because I thought it was obvious. After all, most code is not intended as reuable libraries. /Jorgen -- // Jorgen Grahn <grahn@ Oo o. . . \X/ snipabacken.se> O o . |
| You received this digest because you're subscribed to updates for this group. You can change your settings on the group membership page. To unsubscribe from this group and stop receiving emails from it send an email to comp.lang.c+++unsubscribe@googlegroups.com. |
No comments:
Post a Comment