lilburne wrote:
Olivier Mandavy wrote:
Hello,
i'm looking for guidelines about what are the comments to be written
at the
beginning of source files.
Thanks a lot.
Whatever you think appropriate.
It really depends on what you put in the file. Personally I have one
source file for each class and the comments refer the reader to the
header, which contains an overview of the class and its typical usage.
The most important information though is change history - who, why, and
when, with similar history attached to each function/method in the file.
Ideally each change history should refer to a bug or enhancement
document which gives more detailed information about each change.
One of the things I try to do is make the act of creating a new class as
low cost as possible and if it means that it exists only in one file so
be it. Yeah, sometimes it's not the best thing but it's a whole lot
better than a mash of repeated code everywhere. It's easier to rip out
a class from a file (when you realize what you need some factorization)
than it is to do code surgery. It's also easier to realize two (or
more) classes are easily factorizable than a "Mess O Code" (TM).
Also, the class boundary is rather an artificial place to decide to
"break" into files. I can think of a number of solutions that I would
literally define 100 or so very small very related classes. The
overhead of having all these in different files (i.e. having to compile
the headers for each one for each build) is rather onerous for no reason
that I can imagine.
Also, in many cases I simply want one compilable module that implements
an interface an have absolutly no-one be able to see the implementation
except for the things that exist within that implementation. Sure, I
could use private members but that can still cause linking issues.
A different opinion ...