What should I put in header comments at the top of source files?

Question

I've got lots of source code files written in various languages, but none of them have a standard comment at the top (sometimes even across the same project). Some of them don't have any header comment at all :-)

I've been thinking about creating a standard template that I can use at the top of my source files, and was wondering what fields I should include.

I know I want to include my name and a short description of what the file contains/does. Should I also include the date created? The date last modified? The programmer who last modified the file? What other fields have you found to be useful?

Any tips and comments welcome.

Thanks,
Cameron

Answer 1

This seems to be a dying practice.

Some people here on StackOverflow are against code comments altogether (reasoning that code should be written to be self explanatory) While I wouldn't go that far, some of the points of the anti-comment crowd make sense, such as the fact that comments tend to be out of date.

Header blocks of comments suffer from these symptoms even more so. Every organization I've been with that has had these header blocks, they are out of date. They have a author name of some guy who doesnt even work there any more, a description that does not match the code at all (assuming it ever did) and a last modified date, that once compared with version control history, seems to have missed its last dozen updates.

In my personal opinion, keep comments close to the code. If you want to know purpose of, and/or history of, a code file, use your version control system.