nice styles for code headers

markjugg has asked for the wisdom of the Perl Monks concerning the following question:

Hello,

I'm interested to see some code header designs that folks are happy with. The standard code header we currently use at my development firm includes places for the Title, Version, Description, 4 lines of copyright notice and contact info, 17 lines of GPL declaration, as well as room for a modification history. So it's about 40 lines total with the modification history is empty, and it grows from there. This is all information that seems worth tracking, but it seems like there is a "better way"-- something captures the interesting information, but in less space perl file.

It seems like so reasonable options include pointing people to central document for more information, and depending on CVS to store and generate some of this information.

So if you've got a code header system you're happy with, I'm interested to hear a description or "screen shot". Thanks!

-mark

Comment on nice styles for code headers

Replies are listed 'Best First'.
Re: nice styles for code headers by BlueLines (Hermit) on Dec 08, 2000 at 01:14 UTC
My workplace is an xemacs shop, so we use emacs lisp modes to deal with file headers. This is the generic perl header: `#!/zack/usr/bin/perl # # File: ipchains.pl # # Summary: # # Author: Jon Schatz # E-Mail: my@email.goes.here # Org: foobar.com # # Orig-Date: 17-Oct-00 at 16:33:56 # Last-Mod: 29-Nov-00 at 14:34:55 by jschatz # # Description: # # $Source: /zdevel/cvs/tools/ipchains/ipchains.pl,v $ # $Date: 2000/11/29 22:35:51 $ # $Revision: 1.7 $ # $Author: jschatz $ # $State: Exp $ # $Locker: $` [download] The cool thing about this is that the file header is generated by emacs lisp from CVS info. So as soon as something's been commited to cvs, all the info is automagically written. There's also a disclaimer that gets added to code before it goes production ("This is unpublished proprietary code blah blah blah"), but that's nowhere near as cool as making xemacs generate these headers on the fly. Update: I'll be happy to post up the lisp code to do this for anyone interested. Update 2: Judgment Day: I'm actually going to write an xemacs review for the reviews section, so I'll just put all of the pertinent code there. BlueLines Disclaimer: This post may contain inaccurate information, be habit forming, cause atomic warfare between peaceful countries, speed up male pattern baldness, interfere with your cable reception, exile you from certain third world countries, ruin your marriage, and generally spoil your day. No batteries included, no strings attached, your mileage may vary.	[reply] [d/l]
Re: nice styles for code headers by mrmick (Curate) on Dec 07, 2000 at 22:13 UTC
This is what I've been using : `#!/usr/bin/perl ############################################################### # Program Name: Version: # # Description: # # # Usage: # # Author: Michael Villeneuve Date: # # # Revision History # # Version Date Who #------------------------------------------------------------- # ###############################################################` [download] Mick	[reply] [d/l]
Re: nice styles for code headers by turnstep (Parson) on Dec 07, 2000 at 22:11 UTC
RCS (and probably CVS) are great for storing the version as well as the modification history. You can even have them added directly into your script (e.g. with $Id$ and $Log$ variables). The hardest part is making sure that people enter a short, concise description when checking the source back in after making changes. :) The other things (licensing, title, etc.) are static and can be entered one time, preferably from some sort of template. There is no real way to shorten it other than that - the license, copyright, title, and decription really need to come at the top of the script. I wouldn't think all of that would be needed for every script you write, but that's a management decision.	[reply]