However, it does not support Quarters, which is what I needed. So I have submitted a patch to the project, and have also been using the following code so I can use Quarters now without needing to patch my local install.

The code is not the most elegant, as it duplicates a lot of the code from the library, but until my patch gets incorporated it is the only way to have Quarters.

To use it, download the js file and include it in your web page after the timeline files. You can then use a Quarter in the same way as you would any interval, as shown below:

Timeline.createBandInfo({
    ...
    intervalUnit:   Timeline.DateTime.QUARTER,
    ...
});

Find the code on GitHub, or expand it below:

1. What are Coding Standards?
2. Why do we need Coding Standards?
3. Discussion of Specific Standards
   1. Spaces Around Parenthesis
   2. The Location of Braces
   3. Indenting
   4. Tabs vs Spaces
   5. Comments
   6. Function Headers
   7. Naming Conventions
4. Writing the Coding Standards
5. Publishing and Agreeing the Coding Standards
6. Conclusion
7. Links

Having been working in a team on a large-ish project I quickly found out that we all have very different coding styles. This has provided constant headaches and frustrations throughout the project as we try to work on the same files, re-factoring each others code so it fits in with our preferred styles. Not only is this a waste of time, but it can also make it hard when using subversion to merge changes to the files, as it often thinks the file has significantly changed when really it was only the amount of white-space in the indentation.

In an effort to overcome these problems I have looked into creating some coding standards for my group at work. This article discusses my research into coding standards, including what benefits they might bring and what they should specify.

What are Coding Standards?

Coding standards (also coding conventions or coding guidelines) could be defined as follows:

Coding standards are a set of guidelines that recommend programming style, practices and methods for each aspect of program. They aim to help improve the readability of the source code and make software maintenance easier.

Why do we need Coding Standards?

As defined above, coding standards are designed to help improve the readability and maintainability of your source code. This is important because:

• 80% of the lifetime cost of a piece of software goes to maintenance
• Hardly any software is maintained for its whole life by the original author^[1]

Coding standards help to enforce consistency over different parts of the software when there are a team of developers working together and help make the code more predictable.

Finally it can be difficult to produce and/or read diffs and patches against source code if it does not adhere to any standards, in particular when it comes to white space and indentation.

Discussion of Specific Standards

I will now look at some of the specific coding standards that are often defined in guidelines and discuss whether what benefits they bring and how appropriate they are. They will form the decision of what I include in my first version of the coding standards for my team. This is not a complete list but should capture the main sections of a coding standards document.

Spaces Around Parenthesis

Everyone has their own style when it comes to having spaces around parenthesis. Some examples are:

if(foo)
 
if( foo )
 
if (foo)
 
if ( foo )

Some coding standards define where the white space is acceptable. However, I do not think it makes a significant difference to the readability of the code and so will not be specifying a standard.

The Location of Braces

As with the spaces around the parenthesis, everyone will have their own style when it comes to the location of the braces. Some editors will also be configured to place the braces in a particular location. Below are some examples of braces placement^[2]:

 if (condition) {
    doSomething(); }
 
 if (condition) {
    doSomething();
 }
 
 if (condition)
 {
    doSomething();
 }

I don’t really think the location of braces matter a great matter a great deal, so long as they are sensible and the indenting is consistent. It is not something that is worth defining a standard for, especially at the risk of upsetting people who have their own ideas on the right place to put them.

Indenting

One thing that nearly everyone does agree on is the need to indent your code. This makes the code so much more readable as you can easily see where one code block starts and finishes and if there are nested blocks.

Although it is agreed that indenting is a good thing, there are arguments about how many columns to use for indenting. Most specify between two or four columns, although it really does not matter much as long as it is consistent.

In the coding standards it might be worth defining the amount of columns to use for indenting and a reminder that it should always be used where appropriate.

Tabs vs Spaces

The issue of using tabs to create white space seems to be a contentious one. The problem is the tool you are using might be configured to use tab stops of four, where another persons might be configured to use tab stops of eight, and yet another person might use spaces. So you might have spent some time formatting your code to look nice in your editor, but when the next person opens the file it might look very ugly and difficult to read.

To avoid this issue a lot of coding standards forbid the use of tabs and only allow the use of spaces to create white space. Using only spaces ensures that the code will look the same in all editors and will also avoid problems when printing or emailing code and producing/reading diffs. It should be possible to configure your editor to use spaces instead of tabs (often under the setting of “soft tabs”).

I have certainly found the issue of tabs and spaces to be very annoying and so would suggest that there should be a guideline defined in the coding standards.

Comments

As with indenting, it is generally agreed that commenting your code is a good idea. Comments help to explain what the code is doing, which can be especially useful if it is a complex piece of code. They can also be used to highlight where some code needs later attention, using comments that start with TODO, FIXME or SMELL^[3].

There is a question on how many comments there should be. Some people think you can never have too much of a good thing and therefore your code should be littered with comments. Others might say that if you need a comment then the code isn’t sufficiently simple enough^[4].

I don’t think its worth specifying how many comments people should be writing in the coding conventions. However, it might be a good idea to include a reminder that ensures everyone is using comments where appropriate.

Function Headers

Function headers use comments before a function is defined that documents what it does and possibly more. A function header might be as simple as the following^[5]:

 // This function trims right and left of the string
 function trim(s)

Or it could be a bit more verbose:

 // -----------------
 // function trim
 // input: theString = string
 // returns: middle portion of theString, using the Wiki2001StringAlgorithmNotByKnuth
 // assumptions: theString must be at least 3 characters long (plus terminating null)
 //  to avoid buffer overflow error.  NotKnuthStringLibrary must be opened & initialized 
 //  before calling this function.
 // ------------------
 function trim(theString) {

Like comments, there are mixed feelings about the usefulness of function headers. While they can help to give you an overview of what the function does, it could also be argued that if the code is clear enough then you should be able to work out what it does.

Many languages have their own format for documenting functions in the code, such as Perl’s POD^[6] and Java’s Javadoc^[7]. This can then be extracted and formatted for output in a number of ways, such as HTML and PDF.

Depending on what you are working on function headers might need to be included with the code. However for the kind of projects my group works on it should be enough to specify one or two lines before each function to describe exactly what it does.

Naming Conventions

A naming convention defines how variables, types and functions should be named in a program. This is another contentious issue where most developers have their idea of what is the right naming convention and will not want to be told to do it in a different way.

Naming conventions might need to answer a number of questions. For example, should you use bumpy case, where you use capitalization to divide each word from the next (i.e. formatNumber) or should you use underscores (i.e. format_number). They might also use the name to identify the type of macro, for example a CONSTANT in all capitals, a Class with an initial capital and an instance in lower case. A subroutine would also be lower case and would be clear from context as its usually followed by parentheses.

A famous variable naming convention is the Hungarian Notation and is where the type of the variable is encoded into its name. There is no standard for which characters should be used as the identifier, but an example might be iSize for an integer.

Naming conventions do sound like a good idea. However, different people will have different ideas on the right way to name a type. As long as it is consistent with the names of functions already in the program then it does not really matter how it is done. Therefore, when I wrote my first version of the coding standards for the team I work in I decided not to suggest a particular naming convention.

Writing the Coding Standards

It is worth considering what the coding standards document might look like and how much detail it should go in. Some coding standards are fairly short and concise, such as the BBC’s Perl Coding Guidelines, while others are quite the opposite and provide guidelines for almost all parts of writing code, such as Adobe’s Flex SDK coding conventions.

It is also a good idea to think about the style and layout of the document. Should it be listed as bullet points or discussed in paragraphs?

The coding conventions I think got the best layout are the BBC’s coding conventions for C++ and Perl, and I wrote mine in a similar way.

Publishing and Agreeing the Coding Standards

So I now have an idea of what I want to outline in the coding standards and now need to think about the best place to publish it and getting everyone’s agreement on it. At work we have a wiki, which would make an ideal home for the coding standards as it is accessible to everyone and also editable by anyone.

Once I have published the first version of the standards it will be important to get everyone’s feedback and discuss whether they are the best practices for our group. It will also be important to ensure that everyone feels a sense of ownership for the standards, which will make people more likely to adhere to them.

Conclusion

After completing this research I feel I have a good idea of what makes good coding standards and how much depth they should go into. I have also discussed many specific standards and tried to capture a developers thoughts on them.

You can view the coding standards using the link below. It turned out to be a very short document, but that’s not necessarily a bad thing. I have purposely decided not to define specific standards where we should be able to rely on the developers common sense. Also this is only a first version of the standards and they may well grow as feedback is received.

The success of the standards will be measured by their uptake and whether people feel like they have involvement in the document, rather than just being told what is right. In a months time I will write a follow up discussing how successful the coding standards have been in my group and whether people feel it has helped to improve the consistency and quality of the code.

View the coding standards (PDF)

Links

Since I read so many articles related to coding standards it would probably be easiest to browse them on Delicious. You might also want to see the Wikipedia article.

References

1. Code Conventions for the Java Programming Language
2. http://c2.com/cgi/wiki?CodingStandard
3. Foswiki Coding Conventions
4. http://c2.com/cgi/wiki?MassiveFunctionHeaders
5. http://c2.com/cgi/wiki?SmallFunctionHeaders
6. Perl’s Plain Old Documentation format
7. Java’s Javadoc format

Firecooke is an extension for Firebug and is written by Jan Odvarko, who is also a full time contributor to Firebug. Among other things it allows you to:

• Browse and inspect cookies
• Add, edit or delete cookies
• Log cookie events

Screenshot taken from http://www.softwareishard.com/blog/firecookie/.

I love the way it plugs into Firebug and it provides all the functionality I needed (plus a bit more). For more information about Firecookie check out its homepage.

Incidentally working with cookies in JavaScript is fairly easy. For a good overview take a look at the articles by PPK over at QuirksMode and by Nicholas C. Zakas, or use a JavaScript library such as YUI or jQuery.

References

1. http://mashable.com/2008/11/11/firefox-extensions-for-managing-cookies/

#!perl
 
my @array = (1, 2, 3);
my @newArray = @array; # creates a copy of the @array
my $arrayRef = @array; # creates a reference to @array

In JavaScript things are a bit different. While assigning a boolean or string to a variable does make a copy of that value, assigning an array or an object to a variable actually makes a reference to the value. If your not careful this can easily catch you out, as you might expect to be able to change the new variable without affecting the old object.

Strangely, nothing exists in JavaScript that will help you clone an object. However, other people have came across this and kindly shared their solutions. The code I am now using was submitted by Jozef Sakalos over at the ExtJS forums and is displayed below in a more neutral namespace.

var cloneObject = function(o) {
    if(!o || 'object' !== typeof o) {
        return o;
    }
    var c = '[object Array]' === Object.prototype.toString.call(o) ? [] : {};
    var p, v;
    for(p in o) {
        if(o.hasOwnProperty(p)) {
            v = o[p];
            if(v && 'object' === typeof v) {
                c[p] = cloneObject(v);
            }
            else {
                c[p] = v;
            }
        }
    }
    return c;
};

So to copy an object you can now do the following:

var array = (1, 2, 3);
var arrayRef = array; // reference of the array
var newArray = cloneObject(array); // copy of the array

Links

• Article from Opera
• ExtJS Forum Post

However, there can also be times when the user does not to share this information. Some users might say that it is an invasion of privacy. You might also be coming from a corporate intranet, and are worried about sharing internal URLs with outside servers.

Luckily it is very easy to spoof or remove the referral URL. Some web browsers, such as Opera, allow the user to disable referrer logging^[1], while it can also be removed by the firewall or the anti-virus software. This method uses a small proxy script to trick the browser into thinking that there was no referral URL, as if a user has entered the URL straight into their browsers location bar.

The Script

The script itself is extremely simple and is shown below.

#!perl
 
print <<EOT;
Content-type: text/htmln
<html><head>
<meta http-equiv="refresh" content="0; URL=$ENV{QUERY_STRING}">
<script type="text/javascript">
window.location="$ENV{QUERY_STRING}";
</script>
</head><body></body></html>
EOT

The variable $ENV{QUERY_STRING} contains the part of the link that comes after the first question mark. So for http://andrew-jones.com?http://wikipedia.org it would contain http://wikipedia.org. It does not do anything with the string, so any ampersands or further question marks are left as they are.

The script has two was of redirecting the user. The first uses the meta tag. This tells the browser to refresh instantly (0 seconds) and load the URL that is in $ENV{QUERY_STRING}. As the browser thinks it has just reloaded, it does not send the referrer information with the request.

As not all browsers understand the meta tag, we have also used some simple JavaScript to do the redirect. As you could probably guess, the JavaScript causes the browser to redirect to the location that we have set. This will probably not be used, as most browsers do understand the meta tag.

As a last resort we could also have made a HTML link that the user can click on if the browser will not redirect them, but this will cause the URL of the script to be used as the referrer URL, which may not be desirable.

Summary

So this very simple proxy script will take any URL that’s passed in and redirect the user without the browser passing a referrer URL, for whatever reason you might have. It also works with links that may contain parameters, such as http://www.google.co.uk/search?q=site:wikipedia.org+http. Hope you found it useful.

Links

• Wikipedia Article
• Article on NationMaster

References

1. http://www.opera.com/support/kb/view/93/