Bannering

I am a strong advocate of bannering (ie: the use of boiler-plate comments in source code). Typically, bannering provides some form of "header" to a module and each of its subroutines, together with standard "sections" within each routine for defining its purpose, interface and for stating any assumptions that have been made. It also includes comment dividers that break the code within a routine into logical chunks.

I believe that bannering, along with other coding standards, makes code more approachable and therefore more valuable. It especially helps with maintenance and re-use, where the current programmer may not be the original developer.

Making code more approachable is important to commercial organisations looking to maximise their return-on-investment (ROI). However, such standards tend to be derided by developers who predominantly work on their own because they cannot see the value.

A typical piece of bannering might be:-


Rem *********************************************
Rem * SUB Routine                               *
Rem *********************************************
Sub Routine

Rem ** Purpose **********************************
'The purpose of this routine is to demonstrate
'bannering.


Rem ** Declarations *****************************
Dim variable1 As String             'A String
Dim variable2 As String             'An Integer


Rem ** Routine **********************************
'The real code would start here...


End Sub'Routine


Generally, the bannering would stretch to column 90 rather than to where it does above. Certainly, the variable names and corresponding comments would be much more meaningful!

The banner box at the top highlights the start of the routine. This makes it very easy to locate code while scanning the source. The 'Purpose' section is extremely important and states what the routine does.

Anyone who has ever looked at someone else's code will realise how important this simple section is. It helps people new to the code to immediately comprehend what the aim of this particular routine is. Our internal coding standards at Revell Research Systems stipulate that any input parameters and the return result for a function should be woven into the Purpose section. The Purpose section is mandatory for every routine.

A typical Purpose banner for the VB.Net routine:-

Function Left(text As String, number As Integer) As String

might be:-

The Purpose of this routine is to return the first <number> characters from the left of <text>. If <number> is larger than the length of <text> then the whole of <text> will be returned. <number> must be zero or more, otherwise an exception will be thrown.

Angle brackets are used to identify the routine's parameters within the Purpose text.

The 'Declarations' section is also important. Our guidelines stipulate that all variables used inside a routine should be stated in this section and not declared inline later in the code. The only exception to this rule is for variables declared solely for use in controlling loops, such as in:-

For i As Integer = 1 to 5

   '....

Next

Our standards insist that each declaration should be accompanied with a terse comment that elaborates on the variable's use, although we also expect meaningful names to be used as well to improve code readability. Our guidelines suggest that these comments should start at column 50, but whatever, they should always start at the same column for a particular Declaration section.

Incidentally, we also mandate that full XML comments are provided for declarations (and for such matters as exceptions, etc).

The 'Routine' section marks the start of the real code. We might use further dividers to break up a particularly long routine, but our standing advice is to make the body of routines shorter than one screen so that anyone reviewing the code can see the whole routine on screen without needing to scroll. We believe this cuts down on errors being introduced because some code is out of sight and therefore out of mind.

Subsequent dividers should have appropriately descriptive names to head up the code that follows. Consequently, someone skim-reading the code should immediately be able to see the overall structure of a complicated routine. We use these dividers less now in OOP code, but when developing procedural code from typical Jackson Structure Diagrams (JSDs) such as SSADM 4.3's Update Process Models (UPMs) or Enquiry Process Models (EPMs), we would have made dividers tally with key nodes within these diagrams.

Our commenting standards also insist that routines should have their "end" commented as well. So in VB.Net, End Sub and End Function statements should be followed by the name of the corresponding routine as a trailing comment. This is important because each End statement can then be easily matched with its opening definition.

The Revell Research Systems (RRS) standards also stipulate that code should not exceed column 90, which ensures that code can be printed at a reasonable font size on A4 paper. The various banner lines are mandated to continue to column 90, which also provides a visual cue to programmers when they need to consider wrapping code. Our guidelines recommend that code should be wrapped at logical places within code rather than simply where column 90 dictates. The guiding principal is that no code should ever extend beyond column 90.

We used to also include much more extensive documentation in source code, but with the advent of XML Comments in .NET, we have used this innovation to move documentary comments out into subsidiary comment files. We realised early on that as good as XML comments are, they do clutter the source code.

We insist on heavy documentation at Revell Research Systems because we think this increases the code's value. The ability to provide comprehensive documentation for any code library we have developed to either new team members or to contract developers is invaluable. It helps them get up to speed quickly. It saves us money and improves our profitability.

We also insist that code is commented, where appropriate, to explain what is going on. However, we believe that commenting should not be excessive. Indeed, good code almost never needs commenting. The choice of good identifier names combined with clear code design should obviate the need to explain what is going on. It should be abundantly clear.

Indeed, we review code to ensure that code is abundantly clear. If it is complicated or convoluted, it gets re-written. If complicated code is ultimately proved to be necessary, then we use comments to adequately explain what is going on. We would expect supporting documentation (in XML comment files) to provide detailed explanations of any algorithms being used, together with references to other sources.

These standards (together with code layout standards and the use of proper naming conventions such as those dictated by Microsoft's Design Guidelines for Class Library Developers) are important but are often derided by less commercially oriented developers. I suspect that they concentrate on getting the code to work without reflecting on the importance of reuse by others, simply because they often work alone.

The key point is that commercially valuable code needs to be readily usable and understood by programmers other than just the developer. The more readily understood the code is then the more valuable that code must be. I believe that proper formatting, including bannering, makes code more approachable and easier to share amongst teams. (Obviously, the code also needs to be well-written!)

The problem is that this requires developers to subvert their egos. Developers tend to believe that their code is particularly special. Their style is the best and it provides a way of stamping their identity onto the code. Few home-hobbyists and small developers are open to the prospect of others using their code.

However, commercial code ideally will be reused by others, perhaps long after the developer has left the organisation. An organisation's corpus of code will be much more approachable if it is presented in a consistent way. It will also help to facilitate much greater code re-use, which is one of the Holy Grails of software engineering.

I've insisted on these standards while teaching undergraduates over the past ten years or more. Initially, there is huge resistance, particularly from students who have already been developing code. However, eventually the message that coding standards are extremely valuable does get through, particularly when they start working in teams.

What I do know is that marking well-presented, "bannered" code is much easier. It is much more approachable...!