The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Source Code file header info.

For every source file you create, do you place a header of information regarding it and the project it belongs to?

For example:

/*
Name:
Description:
O/S:
Date:
Author:
Company:

Notes:

*/


Is there some international standard regarding this?
Do I have too much or am missing something? or is it just not worth the trouble and maintenance?

Thanks.
Sebastian Dwornik Send private email
Friday, March 07, 2008
 
 
Not worth the trouble and maintenance in my opinion. What ends up happening most of the time is the next guy comes in and just copies and existing source code file for his new class and doesn't bother changing the header info. Before long, 50% of your code has the exact same header info which makes it worthless.

My motto is to make the code self documenting with the appropriate amount of comments when things get complex. Then apply liberal omments when checking in.
dood mcdoogle
Friday, March 07, 2008
 
 
Why would you need all that? When you check it into source control you'll have the date and name of person. And you should already know what company you work for!

We put a short description of the module at the top of the header plus "refer to task order #XXX for details." In the task order we have the detailed design for that module that gets updated. We also keep those in source control so we have their history.
Bill
Friday, March 07, 2008
 
 
"Is there some international standard regarding this?"

I'm not aware of one.  Depends on the language, or if you use some sort of tool like Javadocs or Doxygen to generate documentation from the code. 

Most projects pick one way and run with it, if they bother to  comment code at all.
Dan Fleet Send private email
Friday, March 07, 2008
 
 
If given the choice I don't do it, but my current job requires it. I see no point, unless you are giving the source code to third parties. Even then I'm not so sure.

My pet peeve is that here at my current gig we have to put a one line summery of each change in the header. Some files have over 200 lines of this junk, none of which is particularly useful, and it's a royal PITA to maintain.
An anonymous voice in the crowd
Friday, March 07, 2008
 
 
A simple macro and the header is added at the push of a button. The company name is a constant, just like the copyright statement. Username and datetime can be obtained easily by most programming environments.

I don't mind, as long as it's not too intrusive.
Eddy Vluggen Send private email
Friday, March 07, 2008
 
 
IMHO the one that you really want to have is a source control expanision string ($Id$ in CVS/SVN for example). In all jobs I've had they always want a copyright statement in there as well... guess for legal if it comes to fighting in court.
EdNoWeb
Friday, March 07, 2008
 
 
Sebastian, I read your post again and you seem to be asking if it is too much... for me it is

I would keep description if things are really going to be described... Name, Author and Date can be (actually should be) retrived from source control...

Notes are worthless to be honest..

/*
Name: --> already know this one right?
Description: --> This one would be good..
O/S: --> mmm...
Date:
Author:
Company:

Notes:

*/
EdNoWeb
Friday, March 07, 2008
 
 
Almost forgot;

You might want to drop the O/S field or auto-add the developers OS to the macro. It would be very time-consuming to check every call for compatibility with all Windows-versions. Would become a nightmare if you were on Mono..

A few small addition to the header; if there's a list of modification-dates, -reasons and names, then why not include the name and date of testing/code reviews?

I'm also quite happy with the URL's that some companies provide, pointing toward the support-forum's and/or code-examples.
Eddy Vluggen Send private email
Friday, March 07, 2008
 
 
"And you should already know what company you work for!"

Unless it is for an external vendor. There should be project documentation that gives this but it doesn't hurt to have it in there.

The one thing I would add is the name and version compiler or development environment.
Anominal
Friday, March 07, 2008
 
 
Your version control system can add a lot of this information into the file for you.  Google RCS keyword expansion for more info.

You can automatically have information such as $Author$ $Date$ and $Log$ (the complete revision comment history) inserted into the file.
Perl Solution
Friday, March 07, 2008
 
 
That's not a bad header, but I think it's a bit overwrought. All I put at the top of my source files is:

  name of unit or program
  copyright notice with modification years
  a quick description of the unit or program
  licensing information (when appropriate)
  a longer description of the implementation, as needed

For each function I also have a little comment block:

  the function's purpose and parameters
  the function's return values
  any special implementation details, as needed (rarely)

This does a pretty good job, I have found, of (a) documenting the code and it's usage, and (b) refreshing my memory when I have to come back to things months or years later.

The comment blocks are not strictly formalized, though they all tend to follow the structure outlined above. I've found that strict formalism tends to breed apathy, and lots of fields get left blank, or, worse, retain (incorrectly) values copied from other files. I also don't put in the kinds of information that is maintained by any version control system worth the name: revision history, version number, etc.

The only really tricky part is keeping the implementation notes up to date. For anything complex the implementation notes can be substantial, so updating them when the design changes is time consuming and error prone. I've long been tempted to move implementation notes out to separate files, but that would only make it even less likely that they would get updated when the designs changed.
Jeffrey Dutky Send private email
Saturday, March 08, 2008
 
 
File headers are usually a source of irritation to me.  I've seen too many standard/required headers that obscure important information by being too large or are so out of date that I can't trust any header.

Sebastian, your header isn't too bad but I do have some suggestions.  First, as others have said, check to see what fields your source control system can pull automatically.  That way, you'll know the information is accurate/up-to-date.

Are the Date/Author fields necessary/useful?  If you have a history/changes entry, that information would be the first entry.

I assume that the O/S field is useful to you since you do PDA development.

Here is the header from a VB6 project I worked on at a previous employer. There are a few things I don't like and would change. The revision info too wordy, it should be a max of 2 lines instead of 5 (3 if you kept the blank line).  The Author and Date fields could be removed - they're just the info from the latest person that checked in the file (and that info is just below it).  We used Visual Source Safe (a piece of crap) for source control and it updated the information between the '$' delimiters.

'******************************************************
' Program Name: MonthEnd
'
' Class Name:  clsAdvBill
'
' Copyright:    <Company>. All Rights Reserved.
'
' Description:  Computes fee information for accounts
'              being billed on this month's cycle.
'
'******************************************************
'
' $Author: <name3> $
'
' $Date: 7/30/04 1:43p $
'
' $History: clsAdvBill.cls $
'
' *****************  Version 3  *****************
' User: <name3>      Date: 7/30/04    Time: 1:43p
' Updated in $/Visual Basic/MonthEnd/AdvBill
' corrected small error in select stmt.
'
' *****************  Version 2  *****************
' User: <name2>      Date: 7/29/04    Time: 4:53p
' Updated in $/Visual Basic/MonthEnd/AdvBill
' Fixed error message
'
' *****************  Version 1  *****************
' User: <name1>      Date: 7/22/04    Time: 11:00a
' Created in $/Visual Basic/MonthEnd/AdvBill
' Initial Check-in
'
'******************************************************


As for function headers, I try to keep them as small as possible with just a description, list of parameters (with valid values or maybe a note, as needed), and the valid return values.  I might add a Comments entry if needed.  Anything more is overkill and won't be maintained properly.
RocketJeff Send private email
Saturday, March 08, 2008
 
 
We do this:

1. Brief description of what the file contains (e.g. "implementation of the foobar module")

2. Copyright and license info.

3. Subversion $Id$ keyword (or your source control system's equivalent).

Don't put things like file name, last modified date, version history, etc in the comment block. You'll never keep it up to date (unless it is auto-genned by your VCS).

Oh, and use Doxygen. It is your friend.
Myron A. Semack Send private email
Saturday, March 08, 2008
 
 
We only put copyright and license information in our file headers, and I have never felt the need to put anything else. E.g. description: the file name should give a pretty good idea of its contents, and if I *really* need a description comment I will put it on top of the function, class or namespace it is supposed to describe.
triple-dot
Saturday, March 08, 2008
 
 
A place I used to work at put the full change history in the file header.  It got out of control pretty quickly, and there was a minor revolt amongst the staff that forced it's removal.

Now, it's just filename, one-line description, and a copyright notice to make the company lawyers happy.
xampl Send private email
Saturday, March 08, 2008
 
 
It's useful to have CVS or subversion (or whatever) keywords like $Id$ and $Source$; the latter is useful especially if you are using CVS and it is not clear where in the repository a given source file came from (due to complext CVS module definitions).  Having a change history in the file is pretty stupid since 1) it is redundant -- that is available from the  source control (eg. cvs log); and 2) more importantly there is no sensible way to do that if you are branching and merging file definitions w/in the source control system.  I guess that's why subversion doesn't have a $Log$ keyword like CVS does.

Will
Will Dowling
Monday, March 10, 2008
 
 
I Usually write a one word sentence defining the purpose of the function, before writing any code.  It helps me to keep the function limitted to its original intended purpose and helps me when I'm going back into some older code to make changes.
Tim Brewington Send private email
Monday, March 10, 2008
 
 
Isthiswhatyoumeanbyaonewordsentence?
Iago
Monday, March 10, 2008
 
 
>>>Isthiswhatyoumeanbyaonewordsentence? <<<

LMAO.  My bad, I meant a single sentence.  If I can't explain what the function is doing in one sentence, it's probably doing too much.
Tim Brewington Send private email
Tuesday, March 11, 2008
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz