Comments at the beginning of source files

[Olivier Mandavy]

Hello,

i'm looking for guidelines about what are the comments to be written at the
beginning of source files.
Thanks a lot.

Olivier

 

[Mike Wahler]

Hello,

i'm looking for guidelines about what are the comments to be written at the
beginning of source files.

Describe the purpose of the file. You might also want
to include indications of the author, revision history,
dependencies, etc. The actual file contents can also
dictate what to write, e.g. if there is conditional compilation
(e.g. via #ifdef), then describe what the macros the #ifdefs
refer to mean.

It's all really up to you. Comments are for making the code more
easily readable and usable (by yourself and/or others).

-Mike

 

[Victor Bazarov]

i'm looking for guidelines about what are the comments to be written at the
beginning of source files.

The language does not require you to write any comments, nor does
it prohibit you from writing a whole novel. It's really up to you
what you want to share with those who you think will read the code
you have written.

If your primary concern for code maintainability, you might want
to indicate the overall purpose of the file, what it contains,
what project it is a part of, your name, who owns the copyright
(if it's not you). Often I see a list of changes in the same
general area as the title comment of the file. However, with
modern version control systems it is really unnecessary.

I am not sure how this is relevant to comp.lang.c++, though.
Perhaps you could tie it closer to the language (to make it on
topic) or go ask the same question in comp.software-eng.

Good luck!

Victor

 

[lilburne]

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.

 

[Gianni Mariani]

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 ...

 

[Peter van Merkerk]

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.

If you use a version control system this is not really necessary. The
same information is (should be) also in the version control system. My
experience is that most people prefer to use the version control system
to see what is changed, when and why. We used to have a macro in our
file comment headers that expanded to the complete revision history when
the file was retrieved from the version control system, essentially
producing what you described. It turned out that nobody used the source
file to look at the revision history, and that was considered to be
noise rather than useful information. Since then that macro was replaced
by a macro which just expands to the current revision number of the file
(which can be useful for example when you have a printed version of a
file).

 

[Gavin Deane]

Often I see a list of changes in the same
general area as the title comment of the file. However, with
modern version control systems it is really unnecessary.

With modern version control systems, IMO including change history in a
comment block in the file is worse than unnecessary. If the change
history information exists in two places (comments in the file and the
version control system's log) then those two will inevitably diverge.
You gain nothing and you risk confusing the next person who has to
contend with discrepancies between the two histories.

This is the same as the argument against writing comments to describe
a piece of code, when the intent is clear from the code itself.

GJD

 

[Jay O'Connor]

This is the same as the argument against writing comments to describe
a piece of code, when the intent is clear from the code itself.

My philosophy is that the comments should say "why", the code itself
already says "how"