Re: Commenting style?
Angel Tsankov wrote:
"Francis Glassborow" <francis@robinton.demon.co.uk> wrote in
message news:Vix6GvdVCzvFFwnr@robinton.demon.co.uk...
[...]
class C {
public:
// ctors
// conversions
//assignments
// mutating functions
// const functions
//operators
//io support
}:
I have no problem with such a style and it does tend to
help maintenance programmers put additions into the
right place (and helps them see what has already been
provided)
Separating member functions (and member data, or course) into
sections seems a very good idea indeed. I would like to call for
more opinions and styles of sectioning since I have found that
putting order in long class definitions makes them much more easy
to understand and maintain.
Avoiding long class definitions entirely helps even more:-).
(Regretfully, it's not always possible.)
In particular, I wonder if it is a good idea to separate mutating
from const functions, e.g. setters and getters. Instead, I would
prefer grouping member functions based on some higher level
criteria. For instance, if a class implements an interface, the
interface members should be put in their own section titled
"IfaceX implementation" or something. Likewise, ctors and dtor
could reside in a section titled "Construction and destruction",
for example. And prorably it is a good idea to put this section
before other sections in the class definition. Also, it might be
fine I tell which members are implicitly defined for a class:
I agree with all points. The public section of my classes
always starts with a section "constructors, destructor and
assignment" (which also includes swap, when present). The
comments in this section explicitly mention anything
intentionally left to the compiler, If copy construction or
assignment has been inhibited by making them private, this
fact is also mentionned there.
Beyond that, functions are grouped. By interface and/or
concept, where relevant. A class which acts in some ways
like an STL container, for example, will have begin(),
end(), front() and back() all together, const and non-const
versions, because STL container is a concept.
When implementing an interface or a concept, it's not rare
for me to use grouping, and no further comments for those
functions except a statement that the group implements such
and such a concept.
--
James Kanze (Gabi Software) email: james.kanze@gmail.com
Conseils en informatique orient?e objet/
Beratung in objektorientierter Datenverarbeitung
9 place S?mard, 78210 St.-Cyr-l'?cole, France, +33 (0)1 30 23 00 34
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]