File headers are a topic of discussion in many areas of the world. Some consider them absolutely neccessary(bad informatics teachers who don’t now what they are talking of, e.g.) while others consider them a stupid waste of time and disk space.
Actually, I did both styles of project. And I have to say that I got to like those headers. However, before discussing the reasons why I love them so much, see the one I use here(feel free to use it as a template, it compiles in OnBoardC and PODS):
/********************************
BinaryClock V1.0
Copyright Tamoggemon 2005
FILE:BinaryClockVfsSelect.c
DESC:Event handler for VFS file selector
CONT:Boolean vfsSelectFormEventHandler(EventPtr pEvent)
EDIT:190905tvh
********************************/
The first two lines are obvious. Program name/version and copyright statement. File designates the name that the file has on your hard disk, DESC describes the file and its history in a few short words. CONT lists all the functions contained(one per line), and edit contains the date of the last editing and the shortcode of the one who edited the file. Pretty simple overall.
But what benefit do they bring to the developer?
Better understanding of a projects “Gestalt”
If your files each contain a little description of what they do and what they contain, it is much easier to get a mental plot of how the fils belong together!
Easier finding of functions
If you ever want to find in which file a function resides, text searching usually is a good thing to do. However, a txt search usually can’t differentiate between definition and call. Now, when you have file headers, a quick opening of the file brings you security!
Printouts are easier to understand
Most source code editors are pretty dumb when printing files is concerned. Syntax highlighting works ok, but that’s it. No banners, haders, footers,.. are placed onto the pages. A formal header makes it a bit easier to identify batches of paper, as you now have EOF-Markers!
Do you do file headers?
Related posts:
Content, RSS
Twitter
They are extreemly useful, but they should be auto-generated and updated otherwise they will quickly become out of date.
Depending on your repository ( and everyone should store their code in a change repository!! ) you can set tags in the header that will be updated at check-in / check-out time.
I use CVS ( it’s free !! ) and have it set to append the filename and path, author, revision and revision date to a file header. Using a simple source tfile template I can add headers to my files in a painfree and efficient way.
Back again,
It’s also extremely important that function protos in the public headers are well commented.
Something like…
/***************************************
Func name:
Func description:
Func parameters:
Func returns: on SUCCESS ->
on FAILURE ->
***************************************/
Hi,
thanks for the detailled feedback!
I have to say that I don’t currently use CVS for knowledge (lack of) and mobility reasons-but it definitely is a great idea!
Do you wish to blog about it maybe?
Best regards
Tam Hanna