Every one talks about coding standards and formats. Some of these rules are good and some are bad and some just don’t matter very much. If you are getting paid to write code follow what ever standard is given to you no matter how bad it is. A happy customer is good to have.
If you are working for yourself you can probably do better. It is easier to work with code if you know what to expect. It is better to have a minimal set of rules that are followed than a big set of rules that are ignored. When I start to modify some new code I will often use tools I have to reformat the code and the comments to my standard.
I don’t like an embedded documentation thing like DoXygen. While it can produce a help file for people who do not have access to the source code, It makes the source code harder to read. Many of the things in the headers can be determined by just looking at the code. When the header is formatted the programmer not only needs to know the language they are working in but also the language for the header.
I often work with source code that has been written many years ago. When I need extra explanation for things in a class or method I put that in the description part of the SnipAssist snip I make so I can easily reuse anything I write.
The examples are for C# but can easily be modified for any language.
Why Headers
The headers in a file break it into pieces to make it easier to see the parts. They make the code look better and make it easy to read.
The file header will say why the file is here and what to expect in it. Often the author or creation date is included. If a big change has occurred I will often put that in the history section. I don’t usually put a project name in the file header because many files are reused in other projects. The exception is for the Form1.cs code file and the Globs.cs file. These are usually customized for a particular project.
The function or method header will have the name and say why it is here. There can be notes about what is does and how it does it. The lines break the listing into parts so it is easy to see where one thing ends and another begins.
To make things easier I have a library of SnipAssist snips for the different kinds of file, class and other headers I need. These make it possible to produce a lot of nice looking source code without all the all the effort of typing. These are useful for new code or for cleaning up existing code. Many headers are part of more complex snips that have some of the item being described.
One reason I have the header standards is to be able to produce certain design documents. There is a program that can extract the header information from the source code files and present it in a formatted report. That will be part of a future blog.
Sample Snippets
These are a few of the header snippets I use most. The descriptions are not shown but describe when to use them. Since a snippet is used for the headers, I have used the macro feature with default values to get even more for the same effort. A similar set of snippets will work with any language. When making a snippet it is better to have too much than too little. It is easier to delete a few lines than is to type them.
I usually replace the contents of the Program.cs file with a start sequence for the kind of program I am constructing. The example is for a simple WinForm program. I use a different snippet when a working folder needs to be found. Also for an editor a different snippet is needed when a command line argument needs to be captured.
//------------------------------------------------------------------------------
//
//NAME: Program.cs
//
//DESCRIPTION: This is the main function for the $"ProgramName"$ program
//
//HISTORY:
//------------------------------------------------------------------------------
//$"ToDay"$ $"Author","JBartel"$ Created
//
//------------------------------------------------------------------------------
using System;
using System.Collections.Generic;
using System.IO;
using System.Windows.Forms;
namespace $"NameSpace","Bartel"$
{
//--------------------------------------------------------------------------
//CLASS: Program
//--------------------------------------------------------------------------
static class Program
{
//----------------------------------------------------------------------
//NAME: Main
// The main entry point for the application.
//----------------------------------------------------------------------
[STAThread]
static void Main()
{
Application.EnableVisualStyles();
Application.SetCompatibleTextRenderingDefault(false);
Application.Run(new Form1());
}
}
}
The next is a file header. When need to add a source file I use an IDE to add a simple class file. I then open the file and use a snip to replace every thing in it. There are two main variations. The first is a new file that has a class in it. When working with Visual Studio I have a partial Form1 class that is similar.
//------------------------------------------------------------------------------
//
//NAME: $"Class"$.cs
//
//DESCRIPTION: This file has
//
//HISTORY:
//------------------------------------------------------------------------------
//$"ToDay"$ $"Author","JBartel"$ Created
//
//------------------------------------------------------------------------------
using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
namespace $"NameSpace","Bartel"$
{
//--------------------------------------------------------------------------
//CLASS: $"Class"$
//--------------------------------------------------------------------------
public class $"Class"$
{
//----------------------------------------------------------------------
//NAME: $"Class"$
//simple constructor
//----------------------------------------------------------------------
public $"Class$"()
{
}
}
}
This header is for a class that is put in a file that already has code in it.
When adding a function from my code library the methods already have headers attached to them. The first header is a simple general purpose one that can go with almost anything.
PineTreeJoe 