You know how you get nagged to document your code? What the file does, who created it, when was it last changed and a history log; all that the QC guy insists that you plug in?
Well, you make an attempt at it initially, and then laziness takes over; you start to copy the header from an existing file to a new one which comes with it's own set of headaches. You have to correct all the previous references to the correct file name, change the history etc.
There is an Emacs package called
header.el that allows you to create the file header and also automatically update certain parts of the header every time you save. There are templates for common classes of file types and the headers generated are self explanatory.
Download the above file,byte-compile it and put it in a place where Emacs can find it. Add the following to your
.emacs.(require 'header) A couple of screenshots should make it clear how useful it can be. Suppose I create a new file called
ccc.sh and invoke
M-x make-header.
This will create a template for shell scripts as shown below. Note that the user name is picked up from
user-full-name which needs to be set in your
.emacs.
The moment I save the file, the "Last Modified" lines and the update count are automatically updated and are done every time the file is saved.
Well, you'd obviously like to put in some revision history and that is done by
M-x make-revision which creates a history section as shown
The commentary inside header.el has more information on customising these features, especially copyright notices and header design to suit your organisation's standards. From the
header.el source file
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Define the individual header elements. THESE ARE THE BUILDING BLOCKS
;; used to construct a site specific header. You may add your own
;; functions either in this file or in your .emacs file. The variable
;; make-header-hooks specifies the functions that will actually be called.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;And user customisable options such as
;; This file adds support for the creation and automatic maintenence of file
;; headers such as the one above.
;; User Commands:
;; M-x make-header
;; M-x make-revision
;; M-x make-divisor
;; M-x make-box-comment
;; Customizer commands
;; register-file-header-action
;; Customizer variables
;; header-copyright-notice
;; make-header-hooksIt's a good idea to put all the changes into your .emacs instead of editing the source elisp file.
One other note: The
emacswiki site has a section on
AutomaticFileHeaders that outlines some improvements over header.el and available as
header2.el done by
Drew Adams. You may want to try that too, though I haven't tried the new version.
