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

Phillisphilly

Answer 1

Date created, date modified and author who last changed the file should be stored in your source control software.

I usually put:

• The main purpose of the file and things within the file.
• The project/module the file belongs to.
• The license associated with the file (and a LICENSE file in the project root).
• Who is responsible for the file (either the team, person, or both)

Resor

I agree. If you are only going to include one thing, at least be decent enough to include the license. – Karleenkarlen

and where will the carefully maintained documented header files go after you compile the code? not in your binaries. License terms and copyright go in the assembly information, the rest is gone or easily replaced never to be found again. I would take the time spent on the header on making sure your requirements are covered in your test cases. – Condemnatory

Answer 2

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.

Inmost

That's assuming all my source code files are under version control :-) A lot of my older ones are not. – Phillisphilly

If they are worth keeping, they belong in source control. – Inmost

+1. Though the "purpose of" the header would only slightly be in VC as part of the commit message; IMHO it's best to put that in the (internal) documentation. And that documentation might be in the same file, depending on style; of course if it's in a separate file, it should also be in VC. ;) – Eyla

I agree with Roger's comment. Information about changes in the file, who changed it, etc. seem best kept in version control, but I like the idea of putting a description of the purpose of the file in the header. – Phillisphilly

Comments are fundamental in programming, especially if code is written by different programmers. A well written code may explain what it does, NOT why it does it and why that specific approach was selected. – Elkins

@DariodeJudicibus That's exactly the opposite of the current general agreement in the industry, which is that comments are for why and not what. Every time I read // checks if the input is null above if(input == null), or // Formats the template above public void FormatTemplate(...), I feel that the author is wasting my time and screen space for no additional value. – Michaeu

Answer 3

Back in 2002, when I was straight out of college and jobs were few and far between after the dot-com bust, I joined a service company which used to create software customized for their clients in Java. I had to sit in the office of a client (which was a ramshackle room in an electric sub-station rigged with an AC to keep the servers running), sharing chairs/PCs with other guys in the team. The other engineers (if I can call them engineers ;) in the group used to make changes ad-hoc to the source code, compile the files and put them into production.

• No way to figure out who made what change.
• No way to figure out why any change was made.
• No way to go to previous version of code, unless the engineer "remembered" what he modified.
• Backup: Copy over files from the production server, which were replaced with new files.
• Location of backup: Home directory of engineer copying over files to production server.

Reports of production servers going down due to botched attempts of copying over files to the server (missed a file to be copied over, backups getting lost or wrong files being copied over or not all files being copied over) were met with shrugs (oh no, is it down? let's see what happened; hey who changed what recently...? ummm...).

During those days, after spending several frustrating days trying to figure out the whos and whys behind the code, I had devised a system for comments in a list in the header of the source file which detailed the following:

1. Date of change made
2. Who made the change
3. Why was the change made

Two months later when the list threatened to challenge the size of the source code in the file, the manager had the bright idea of getting a source version control system.

I have never needed to put any comments in headers of source files (except for copyright notices) in any company I worked since. In my current company, everything else is mostly self-evident by looking at the code, or going to the bug reporting system which is integrated with the source version control system.

Consolation

Answer 4

What fields do you need? If you have to ask whether to put some info there, you don't really need that info. Unless you are forced, by some bureaucratic incompetence of your employer, I don't see why you should go looking for more info than you already feel should be there.\

Pyongyang

Point taken. I was just having a good poke around in my source and I realized that my headers (if there were any) were completely inconsistent. I was asking the community for what they put because I'd like to know what they find useful (or not) to have, and by extension what I might find useful in the future (I don't really know what I'll need until the day I need it, which is too late :-) – Phillisphilly

Answer 5

You did not mention that you are using a version control system and your comment in Neil N's answer confirms this for your older code. While using version control is the best way to go I also have experienced many situations where the cost of doing so for older code would not be paid for by the project's sponsor. If you do not have a centralized change history for the project then the change history can be put in the modules. It is good that you are using a version control system for your new code.

Your company name
All rights reserved (c) year - or reference to appropriate license

Project or library this file is for

Module it belongs to

Description of what it contains

History
-------
01/08/2010 - Programmer - version
  Initial creation.  
01/09/2010 - Programmer - version
  Change description.
01/10/2010 - Programmer - version
  Change description.

Dardani

Yes, version control is a must-have for all of my new projects. Unfortunately, many of my earlier ones aren't under version control because I didn't know that it existed back then! It's too late to add a version history to my old files now, but the top section of your suggestion looks good to me. – Phillisphilly

Answer 6

In most organizations, all source files have to begin with a legal blurb. If you're really lucky, it's just a one-liner, but in most cases it's a really long block of legalese. As a result, few people ever read these. Our eye just travels to the first program element and then goes up to its documentation.

So if you want to write anything, write it in association with the topmost program element, not the file.

Any other bookkeeping information should generally be part of your version control, not maintained (poorly) in the file itself.

Wirewove

Answer 7

In addition to the comment above stating license, the project that it belongs to, etc I also tend to put the "weird" requirements at the top as well (such as "built with version X of library Y") so you, or the person who picks it up after you won't change something that the program relies on without realizing it (or, if they do, they will at least know what to change back)

Detrimental

Answer 8

A lot depends on whether you're using an auto-documentation generation tool or not.

While I agree with many of the comments, if you're using JavaDoc or some other documentation generating tool that depends on comments, you'll obviously need to include the things it wants to see.

Santosantonica

Answer 9

English is a communication language right? Java is a programming language, right? Use English to talk and Java to program!

After years of software development and relationships with the software developers as human beings, I can report that in 100% of the cases I found, the same people advocating for zero-commented code are also the same people that take forever to answer when asked what their own code does if more than a month has passed between the code writing and the question. Often I could even give an answer before them, which is just ridiculous!

To anyone reading please, please comment as much as you can, people reading after you will be so grateful instead of insulting you.. or at least, insulting you lot less!

Duluth

I totally agree with everything you said, but I think a straight statement at the very top of the answer like "You should talk about what the code does" will make the point even clearer. – Osprey

Every language is a "communication language". Java is a high level programming language; it's made to communicate your intent to another programmer. If it was made to talk to a computer, it would just be machine code – Michaeu

Comments are there to express things that you can not express in code, like e.g. a weird workaround for a 3rd-party library bug. It's a helpful and necessary tool, but every time your code isn't clear without a comment, try to make it clear first. Your people have done neither, so I understand why you prefer comments everywhere. But that's not a way to write easily readable code - it just allows you to work with code that's not. SOLID principles help a lot with writing readable code, especially SRP. – Michaeu

Answer 10

Those useful fields that you mentioned are good ones. Who modified the file and when.

Your version control software should allow for the embedding of keywords within comments. For example, in CVS, the $Id$ will resolve to the file, date/time modified, and user that modified the file. It will automatically be kept up to date with each check-in.

Carcinomatosis

But if you're using source control, why do you need comments? – Pyongyang

Answer 11

Include the following information:

• What this file is for. That's a very useful piece of knowledge and it's more important than anything else. You should tell the reader, why there is such a file, why did you group functions in a separate file/package/module and why they are used. Maybe briefly, one or two lines, but that should be there.
• Legal stuff, if appplicant.
• Leave the place for special commands of console editors, such as of Emacs.
• Add special commands that your auto-documenting system requires.

Things things you shouldn not include are

• Who created the file
• When it was created
• Who modified it the last time
• When it was last modified
• What was added by the latest modification

You can--and should--retrieve it via the version control system, where it's constantly and automatically kept up-to-date. Let alone that most of these points are just useless.

Skysail

The last modified date is valuable information in the file header when the file is copied from project to project, and they need to be compared later. – Arnulfoarny

Answer 12

Who created the file When it was created Who modified it the last time When it was last modified What was added by the latest modification

Rhineland

Answer 13

Though many arguments are presented about not having file headers, I think file headers still have validity.

Put the name of the module/class/function and to which library or logical section it belongs, and add a last modified field.

Those are the primary fields helpful in cases where the file was erroneously moved, renamed, etc. The last modified date helps developers, especially in cases where the file has been copied to another project and needs to be compared against the original project (Git can’t help you with that).

Example

/* Notification Log ID Module [Common Notification]
 *
 * Last updated: August 12, 2023
 */

If your organization requires you to keep a copyright notice, put it in a separate comment section below the file header. It makes it easier for developers to collapse the copyright statement while keeping the file header open to read.

Arnulfoarny