Programming Guidelines I Have Followed Since 2001
In my last job, 23 years as Technical Director for a digital agency, I headed the development team through many different frameworks, systems and languages. We realised very quickly that we needed a set of solid programming guidelines to follow and in 2001 we set down to write them. I have tried to follow these guidelines ever since.
Obviously, as such a big chunk of my life, I mention working for Headland a lot and we had some great clients such as Alton Towers, Santander, National Geographic, and Leicester City Council to name a few.
The development team grew to a handful of people in just a few months from the Leeds office being opened and we had been lucky enough to have some high-profile financial companies and banks as our clients.
Because of this, there was a need for a guideline document for the developers to work with.
The standard version of this document amounted to 23 pages and reached its pinnacle at version 4, updated in 2014. It consisted of sections such as documenting your code, connecting to SQL databases and building secure sites. but the area I am going to focus on in this post was section 1: general guidelines. We wrote them in 2001 when we were building websites using classic ASP but they are pretty much as relevant today as back then even when you take into account moving towards .net, CMS and mobile development.
One thing to note is that the document was obviously a confidential document, but the company doesn't exist anymore and I haven't highlighted any of the more specific guidelines which would be sensitive, these are just general guidelines that I think everyone should follow to some extent.
Some of these guidelines were based on personal choice, others on common sense and with very few exceptions, I still follow them.
- Code should be correctly tab indented making it easier to read.
Of course, there is an age-old argument between those programmers who use tab indenting and those hobbyists who space indent 😏 However, in our eyes as a team, there was no doubt that the best solution for us was to tab indent our code. It's easier to read, uses fewer characters and you can dynamically change the tab indent size in most code editors.
We hadn't considered space indenting because we weren't monsters! ;) - Code must be commented.
Working as a team, you may be required to work on someone else's code in their absence, or you may be requested to work on some code that you wrote months earlier. Therefore, it clearly makes sense to document your code, especially if it does something complex or out of the ordinary. It doesn't need to be every line, just where you think it necessary or useful when revisiting it. - Use local variables in subroutines and functions. Local variable access is faster than global variable access. Use of local variables also tends to make code cleaner and avoids data getting mixed.
This is not as relevant nowadays as in the days of Classic ASP. c# has a much more developed scope system which requires local variables as a default, but it's useful to understand the reasoning nonetheless. - Use Pascal casing (FirstName) and meaningful names for all your variables, functions, objects etc.
Avoid non-descriptive or highly abbreviated variable names; spell out what each variable stands for (e.g., "TotalInvoiceAmount" not “Amount” or "TtlInvAmt"); "i" or "x" are fine when just running a "for" loop.
When naming functions, include a description of the value being returned, such as GetCurrentUserName()
This guideline goes hand in hand with code commenting. Sure, Pascal Case is a matter of preference and is the only guideline I don't follow nowadays preferring to use Camel Case instead, but this is only because I develop within the Umbraco CMS a lot nowadays which favours Camel Case (and I find it easier to read when differentiating between variables, commands and keywords). The main point is to keep them consistent.
Naming your variables and functions in a way which describes what it does or what it returns just makes it easy when you come back to your own code or read someone else's. - Create reusable code libraries.
Repetitive or package-able tasks common to multiple functions, or used by several pages, should be moved to common "include" files.
Configuration parameters such as connect strings, passwords, and other elements that can vary from implementation to implementation should always be defined as constants that are contained and isolated inside their own configuration file - which should be inside it's own directory wherever possible. This allows values to be amended without modifying any executable code.
As before, this was in the days of Classic ASP and .net development within c# has a facility for storing configuration data in separate files (we were ahead of our time) but also it makes much more sense to break your code down into reusable functions because the likelihood is that over the years you'll create a library of routines you can keep coming back to. A sort of mini personal npm or GitHub (why didn't we think of creating a global library or package manager in those days, we'd be rich now!) - Use client side validation when possible but all data must be validated server side too.
This is very important, there's a lot of emphasis on user experience and usually, that means a nice slick client-side validation interface... But this HAS to be backed up with server-side validation, an accessibility user may have problems, or using a browser that doesn't have javascript enabled, or a hacker may turn off client-side scripting so they can post bad data to the server... So, make sure you validate, validate and validate again at every level. - Copy individual values from collections into local variables if you are going to reference the value more than once. This saves the runtime engine from having to perform lookup processing in the collection for each and every reference.
This is good practice, when working with other people's work you often see the code get configuration data from the database or from a text file and then re-get it multiple times within the script.
Nowadays, programmers cite that it doesn't matter because databases have access to great memory caching so the speed is irrelevant but there are many factors involved such as network and CPU latency (especially on virtual servers) and it's just quicker if it's reading from a local variable. - If you are going to loop through a long recordset, consider loading it into an array using the Recordset.GetRows method and close your recordset before you process it.
Again, the specific example given is geared more toward classic ASP but it's still good practice regardless of the language you are developing in if working with long recordsets. I guess the caveat is that if your website is heavily hit you may need to rethink as storing long datasets from millions of hits will quickly gobble up the gigabytes. - Handle errors gracefully. Errors should be handled and appropriate user-friendly messages displayed. Don’t assume that things will execute correctly.
Oh please, this is common sense, isn't it? You'd think so but there are so many examples of applications and websites that just crash on a whim giving the user just a 32 bit error code... Please make your interface as user-friendly as you can and test, test and test again. - Module comments should include a section at the beginning (top) of the module that identifies the name and purpose of the module.
In-stream comments throughout the code describe the functions being performed, explain any unusual techniques, and tell why any surprising techniques were performed the way they were. At the same time it is not important to comment every line or every common technique each time it is used. If something is obvious there's no reason to comment it.
Any internal "Sub" or "Function" routines in the code should contain comments at the top that identify the name and purpose of the routine as well as a description of any calling parameters and return values.
This again is team preference, and you may decide on a different way of doing it, but the end game is the same, comment your functions so you know what they do when you or someone else next visits it.
I hope that giving you an insight into our age-old documentation is at least interesting to you and who knows, it may make you think about the way you code. Either way, it does show that even 20+ years ago we had to consider how our code affects us as a team, the client and the user.
I really could do with your help! 😃 If you find this article interesting, could you please do me a favour by either sharing it or commenting below, I would love to hear yours and other peoples' thoughts on this subject. And if this or any other content on the site has helped you and you would like to show your appreciation, then you can always buy me a coffee ☕️ It would make the time I put into this more than worthwhile! Thank you 😃
Author: Craig Pickles (YorkshireTechy)
Hello, I'm YorkshireTechy. My name is Craig and this is my personal/portfolio site, I use it as a way of writing down my thoughts, showing off my skills and documenting my work.