Are comment headers and footers in your code really necessary?

Question

Many corporate coding standards require a large comment header and footer in each and every file. Something like:

// MyFile.cpp
//
//  Copyright (c) 200x Company ABC
// 
//  This file is a copyrighted... blah blah blah
//

<... some code ...>

// Copyright (c) 200x Company ABC
//
//  Change history:
//     1.0  -  Blah
//     1.1  -  Blah, blah..

So, the question is - why do we need this? Is this really necessary to claim copyright for the contents of the file, or is it a misguided practice that has become standard? Anybody out there work for a company that does NOT require something like this?

Answer 1

I work in a company and we do not require this. We have copyright for what we do by default, so it's just unnecessary text noise in a source file.

Change history can be useful but very limited. If you will attempt to make a record of each semicolon or operator you change, it's gonna get old very soon. Moreover, change history does not give you much details on what exactly a particular author has changed. It's rather who's been here and did something.

Answer 2

It is not necessary to claim the copyright (depends on the jurisdication). You usually have the copyright automatically for your work.

For code within a cooperation it is always nice to know how did what and when on a sourcefile.

I have never seen internal code without some kind of header/footer combination.

Answer 3

My company doesn't require this... and the place of the change history should be in the source code control instead of the code file.

Answer 4

First, the change history is pointless, use your SCM for that.

A copyright statement is not strictly required (copyright is automatic)¹, but if you are publishing source then likely including it will be felt to be safer². The full licence statement would probably be better in a separate file and then referenced (this is what Boost does).

¹ Wikipedia has a reasonable summary, but you really need to take your own legal advice.

² Especially by lawyers playing it safe.

Answer 5

If this comes to corporate standards we haven't it at all. But in spite of this we adds copyright statement and contact data at begining of every file when this file is supposed to be distributed or supposed to be in use by other facilities. It helps in feedback gathering.

Answer 6

I work at a very large software corporation, with many many weird standards.

This is NOT one of them. We are not required to add any headers or footers to our source code. Copyright does not need to be stated on each class file. not to mention revision, which are handled by any source control management system available.

Answer 7

In the company I had my internship in we used these standard comment headers in all source files - boy they annoyed me. Everytime I had to read a new source-code file I had to scroll 1 or 2 screenlengths down because of all change-history each file had. In the 6 months I were there I never used the change-history at all, and never saw anyone who did.

My personal oppinion is that you shouldn't place stuff that you'll rarely need such a place. You need to have the change-history and stuff like that somewhere ofcourse, but it should be somewhere that you could look up in case you actually needed it. Maybe in the footer if you insist on embedding it into the source files?

Standard header comments are a pain, and should be VERY minimalistic or even better non-existing. Throw that huge ASCII-art down to the footer or into the readme, I don't care, but please, leave my header alone :)

You think google wouldv'e been a success if the first 800 pixels of your search result was populated with some huge google logo and copyright statements? :P

Answer 8

The change history requirement in the header could be a left over from before they had a change history system in place. I have worked with systems where the comments were made manually and would create fake changes in the source control system!

Where I work currently copyright and change history are not required in code file headers or footers.

Answer 9

Interesting to see that Google require copyright notice on their C++ souce. This has always seemed superfluous to me, especially given the files will (hopefully!) be backed up and also reside in Source Control, in case a copyright battle ensues. I'm also unsure of branding the source with the author's name: do other people need to ask for permission to edit/use the file?!

Source Control definitely eliminates the need for a change history footer, and the weird practice I have witnessed of people commenting out old code and leaving it there! Good SCM software will let you browse file revisions and provide version comparision anyway. Good question :)

Answer 10

A lot of this stuff is historical hangover. But that doesn't mean it's useless.

Commenting the changes on a file is pretty pointless, the file stopped being the unit of code organisation many years ago. I put headers on my functions, but that's to explain the purpose of the function/method (plus it makes the code easier to scan). I also put concise change histories in those function headers... not because a change history in code is necessary, but because SCM systems aren't perfect, and I've seen SCM databases lost before. It's like backups - the disaster only has to happen to you once before you start worrying about this stuff on a daily basis.

My buddies at work drive me nuts because they rely religiously on the SCM to track their changes, but don't put proper comments in the SCM either. So when the inevitable management post-problem fault-analysis happens they have to sit there for hours on end trying to figure out why they made a given change three years ago.