Re: Subroutine header

Hi Stefan

I used to write headers like those, these days I lean more on my
toolset to keep that kind of information for me. For example:
-- I use the Subversion version control system to maintain key
information (such as revision, last modification date, etc) in source
files.
-- I use a build script which writes a build log containing all the
compilation and linking details. These logs go into the version
control system, and I use the MD5 hash of the built executable in the
log to ensure that I can later tie the two together without doubt. We
use several compilers here, spend a lot of time tuning the options, so
need an automated way to record this info -- which 'belongs' to the
binaries anyway, not the source code. Make make your friend (or learn
SCons or use your favourite scripting language).
-- I no longer keep modification details in source files. I write
notes in comments as I develop but when the code is submitted for
build for production release I (in line with site standards) strip out
all such commentary. In my experience (guess who wrote the site
standards) most of the modification notes I ever saw were useless,
even the ones I wrote myself a short while later. One of my
colleagues used to never delete a line of code or commentary from any
source file when he modified or enhanced it. After the ratio of
commented out lines plus comment lines to code lines goes over 5:1
(say) you begin to understand why some people say all comments are
bad.
-- Argument details go in comments next to their declarations at the
head of sub-programs.
-- We have an old utility knocking about (called ???) to create call
graphs. If I was concerned I'd use it rather than rely on what
someone may or may not have written correctly and clearly into a file
header. Lots of interdependencies between modules and programs make
this unsuitable for source file headers anyway.

So, my general rules are these:
a) If file header information can be maintained automatically then use
the right tool to maintain it.
b) If it can't be maintained automatically then it won't be maintained
manually, so don't bother.
c) If you don't have the right tool buy it or build it -- it will
always be worth the expense or effort.

In spite of (b) I do put into file headers comments about the intent
of the source, perhaps a specification of the algorithm it implements
or the problem it solves.

Regards

Mark Westwood

On May 11, 10:58 pm, Stefan <stefan@xxxxxxxxxxxxxxxxx> wrote:
When writing programs/subroutines I usually give them 'header' like
this:

PROGRAM/SUBROUTINE EXAMPLE(a,b,...)
! Version: 1.01 Last modified: 11.01.2001.
! Parameters: a - first parameter
b - second -||-
! Calling: list of subroutines it calles, if any ...
! Part of: if part of a greater program (exclusivly)
! Compiled and tested with: CVF66c
! Modifications:
! - version number / date:
! short description of modification

Do you have a similar habit and what do you include in those headers?
How do you organize larger programs and determine what a certain
subroutine does after not looking at it for a while ?

Stefan

.

Relevant Pages

  • Re: #include question
    ... > (translation units as I found them called in Bjarne Stroustrup's book). ... > I know about multiple inclusion guards, ... Correctly written headers, which includes standard ones and should ... classes and structs do nothing until a source file instantiates them ...
    (alt.comp.lang.learn.c-cpp)
  • Header include order
    ... - include system headers ... include application headers ... include the header associated with this source file ... Does anyone have a reasonable justification for the standard include ...
    (comp.lang.c)
  • Re: Larkin, Power BASIC cannot be THAT good:
    ... headers), and no platform-specific macros. ... one source file. ... doesn't have classes, Java doesn't have pointers, or half of C++'s OO ... So the only languages that allow 40-year old programs to be simply ...
    (sci.electronics.design)
  • Re: #include "string.h"
    ... since any program does use some standard headers anyway. ... if you put string.h into the folder next to the source file, ... more than what it's talked about in 7.1.2p1 (or the intent for it ...
    (comp.std.c)
  • Re: #include <all> [Was Re: novice: small annoyance]
    ... >>precompiled headers or some other accelerating mechanism, ... >>almost every compilation slower, and few people would use it. ... More main memory means less paging. ... If your system spends most of its time paging data in and out during ...
    (alt.comp.lang.learn.c-cpp)
Loading