Goto Blog Home PageRevell Research Systems: Alastair Revell's Web Log
On this page....
<February 2020>

RSS 2.0     Atom 1.0     CDF

Blog Roll
About Alastair Revell
Alastair Revell is the Managing Consultant of Revell Research Systems, a Management and Technology Consulting Practice based at Exeter in the United Kingdom.
Contact Alastair Revell
 EMail Revell Research Systems Limited Email Me
Legal & Other Notices
Sign In
The material published in this web log is for general purposes only. It does not constitute nor is it intended to represent professional advice. You should always seek specific professional advice in relation to particular issues. The information in this web log is provided "as is" with no warranties and confers no rights. The opinions expressed herein are my own personal opinions.

Web Log Home | Welcome to this Web Log | Using this Web Log | New to Blogs? | About Revell Research Systems | Contact Details

Review Entries for Day Saturday, June 10, 2006

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

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



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...!

Monday, September 03, 2007 2:41:34 AM (GMT Standard Time, UTC+00:00)
Nice Post Alastair - I like your idea of “bannering” code with respective comments. The best way I have used to do this in .NET is to write a macro function which, when executed, extracts the name of author from a variable, extracts the function name, parameters etc. in XML format and generates an XML banner with the tag empty, where a programmer can put in the relevant comments. This is not only fast but also time saving. This can even be made simpler to reduce the clutter.

These XML comments can then be read by any documentation generation tool (like NDoc or JavaDoc) to generate code documentation in CHM format.
Tuesday, September 04, 2007 9:11:55 AM (GMT Standard Time, UTC+00:00)

Thanks for the comment.

We use a series of macros in Visual Studio to generate the banners for each routine. These are rendered as plain comments. We also use XML comments extensively, but we normally (almost without exception) use include tags to reference an external XML comment file from the code to reduce clutter.

The idea behind the comments included in the banner is to give a programmer sufficient detail about the purpose of the routine and its variables to understand what it is trying to achieve without having to refer to the more in depth help, which focuses on special cases, exceptions and examples.

Comments are closed.
RSS 2.0 Feed If you enjoyed reading an article on this blog, why not subscribe to the RSS 2.0 feed to receive future articles?
Revell Research Systems Logo Visit the Revell Research Systems Web Site if you want to learn more about this management and technology consulting practice.