Coding Standards, Naming Conventions and Formatting Styles

Written by Stéphane Richard (Mystikshadows)


AS you've read from the title of this article, it is all about coding standards, naming conventions and style of your source code module. The mean reason I've created this article isn't to brainwash you into my way of doing things. This article is not the first to talk about such a subject. But what i have elaborated here have proven themselves worth my time on all my projects both professional and personal. There's more than one reason to do so as you'll read here and to the best of my knowledge, following these standards and conventions, that you created yourself, might take just a bit more time in the programming phase of your project, but it can easily save you alot of time in the debugging phase. Likewise, because these are your standards made to follow your coding methods, it doesn't really take any of the fun out of your programming project.

The main thing to remember in this article isn't the standard itself (although you're more than welcome use it if you like it) but rather to give you the reasons why coding standards exist, why they can bring benefits to your projects, even the smallest ones. It takes a little mental training to motivate yourself to create this standard, take the extra time to name your variables, subs and other elements with clear and relevant names. But you'll be the first to reap the rewards of implementing these practices into your own programming endeavors. Note that I am using the standards I've elaborated in the 3rd part of my Graphical User Interfaces - A Complete Study So the standards might look familiar as it is the standards I follow on any of my projects (big or small). I will however elaborate on them in more details here. So then, Let's get right to it.


This is always the bigger question isn't it? Of course, if you can't find a reason to create a standard, chances are it will be hard for you to actually create one and even more so actually follow the standard you set yourself. What I will do here is give you the reasons why I created my own standards, and what benefits they've given me so that you can see for yourself what standards and conventions are really all about.

I don't know about you, but by reading these advantages, I'm sure just those got you thinking all of a sudden. It's clear to see that good standards and naming conventions really helps make things more prepared for the unevitable future of programming, changing existing code, adding new code in and remembering what you did 5 years ago. If you could find a way to give you all these "easier things in a programmer's life", wouldn't you want to alteast give it a good try? It doesn't take a bachelor's degree to create a standard and you don't need rocket science to be able to stick to it. All you need is the time to create it. In my case it took about 2 good hours of thinking and writing. So it's not that much time. But the time it will save you in the long run can be alot more than you would think possible.

So then, with all this in mind, the next logical step is to simply go right ahead and elaborate these standards. It's very important for you to remember that these are the standards I created and like to work by. They might sound interesting to you and as such you can definitaly used them if you want. Some of your might feel that only part of this elaboration wight be usable in your case. Again, feel free to use this in whole or in parts. The real idea behind this whole article is to help you find a way to organize your code in a way that will help you work on projects without being overwhelmed by the code you have done or the code you are about to undertake. Simple organization prior to coding as well as some common sense is really all it takes. So het's talk about these standards.


The standard I'll be using is broken down into three workable standard groups. These are the "Source File Documentation", "Indentation and Spacing" and "Naming Conventions". As I mentionned, coding standards are there because when the code gets big, it's clarity will have better chances at staying as clear as possible across the thousands of lines of codes there will be. Let's take the time to review these standards right here.


In big projects, if you don't implement error management right from the start, it will be a major headache to add it later in the project or at the end after you're done coding everything else. For this reason alone I talk about error management as part of a convention because like the rest of your standards and conventions, they need to be implemented from the start so they don't quickly become quite an overwhelming task. However, doing it from the start like this, you can integrated it easily to your coding routine and almost not have to worry about it. At the end you'll end up with all your error management done and be ready to move on to the next step of your project right away.

Throughout all the modules, each sub and function, when implementing the error management code, you might want to think about the reasons why you are implementing error management. As far as I'm concerned One of the main reason I implement error management is because of the debugging phase and the other errors that might occur afterwards as users actually use my program. As such, I need a system that can point me as close as possible to the erroneous code. This way I don't have to spend too much time locating where the error is actually happening. For that to successfully occur, I need a certain list of information to help me in my quest. Whether the bug is reported on screen or logged to a file this information will still help locating bugs quickly. Here's that information: (note that this is also in my 3rd part of my GUI series).

Error Information Description
Engine Name
Module Name
Sub/Function Name
Parameter List
Error Number
Error Description
The Engine name is displayed
The Name of the .bas or .bi file
The Sub or Function Name
The values of the parameters passed
The error number as returned by ERR
A human readable description of what the error means

This essentially means that whenever an error is returned by the system, it will give me back these specific pieces of information. By knowing right from the start, the Engine where the error occured, the module name, the sub or function name, the values of the parameters that were passed to that sub or function (if any) and the error that occured, imagine how fast the debugging process will suddenly become for me, or anyone else correcting the error. Here is an example of a typical function and how I will provide the needed information. Let's assume that this function will be in a module called MouseControl.bas and that the project is called DrawingPad:

' ============================================= ' NAME: MouseOverControl() ' PARAMETERS: XPos AS INTEGER ' YPos AS INTEGER ' Width AS INTEGER ' Height AS INTEGER ' MouseX AS INTEGER ' MouseY AS INTEGER ' ASSUMES: Parameters are positive values ' RETURNS: True if mouse is on top of the ' control, False if it is not. ' CALLED FROM: EVRIL's main logic loop. ' --------------------------------------------- ' DESCRIPTION: This function will take the ' position and dimensions of a ' control, do the math to get ' the range of coordinates that ' the mouse need to be in to be ' considered to be on top of the ' control and compare the mouse ' coordinates to see if it falls ' within the control's range. If ' it does, True will be returned ' to the calling sub. If it's ' not on top of it, False will ' be returned instead. ' ============================================= FUNCTION MouseOverControl(XPos AS INTEGER, YPos AS INTEGER, _ Height AS INTEGER, Width AS INTEGER, _ MouseX AS INTEGER, MouseY AS INTEGER) AS INTEGER ' ------------------------------------------------ ' We create a variable to hold the error message ' ------------------------------------------------ DIM ErrorMessage AS STRING DIM BottomRightX AS INTEGER DIM BottomRightY AS INTEGER DIM WorkResult AS INTEGER ' -------------------------- ' Turn in Error management ' -------------------------- ON LOCAL ERROR GOTO ErrorManager ' --------------------------------------- ' Evaluate the bottom right coordinates ' --------------------------------------- BottomRightX = XPos + Width - 1 BottomRightX = YPos + Height - 1 ' ------------------------------------------------------------ ' Compare Mouse coordinates to control's area and return the ' proper value of the function based on if the mouse is over ' the control or not. ' ------------------------------------------------------------ IF (MouseX >= XPos AND MouseX <= BottomRightX) AND (MouseY >= YPos AND MouseY <= BottomRightY) THEN WorkResult = True ELSE WorkResult = False END IF ' ------------------------------------------------------------- ' Return the value and exit the function right here before ' execution of the error management section can take place ' if no error occured. ' ------------------------------------------------------------- MouseOverControl = WorkResult EXIT FUNCTION ' ------------------------------------------------------------------- ' This is where the error management message is created and printed ' ------------------------------------------------------------------- ErrorManager: ' ------------------------------------------------------- ' First step is to formulate the complete error message ' ------------------------------------------------------- ErrorMessage = "Engine: DrawingPad" + CHR$(13) + _ "Module: MouseControl.bas" + CHR$(13) + _ "Function: MouseOverControl" + CHR$(13) + _ "Parameters: (" + STR$(XPos) + ", " + _ STR$(YPos) + ", " + _ STR$(Height) + ", " + _ STR$(Width) + ")" + CHR$(13) + _ "Error: " + STR$(Err) + ":" + Err$ ' ------------------------------------------------------------- ' Next we either display the error or append it to a log file ' ------------------------------------------------------------- IF ErrorLogging = True THEN LogError(ErrorMessage) ELSE DisplayError(ErrorMessage) END IF ' --------------------------------------------------------------- ' In this case, we resume execution loging or showing the error ' --------------------------------------------------------------- RESUME NEXT END FUNCTION


And there you have it, the coding standard documents comes to an end. If you've paid attention, you can see that the major factor you need to remember when creating your coding standards is that they have to make sense to you now and in a year or 2 if you need to get back to that same code. If just that stays in your mind after reading this, I will be able to say mission accomplished. Too many times I've seen people code away for months, leave to work on another project and be baffled when they need to get back to that project. Too many times I've joined projects that didn't follow any standard imaginable. It's really amazing what a couple of hours (maybe a days work) defining a standard can do to the overall coding process. How much it can help during and after the programming phase. This is the major reason why I wrote this article. Is to make you think about it.

What's to say next? Are you going to create your standards or keep working the way you are now? That decision is up to you some might have the natural gift to code so clear that not understanding what's happening is simply not an option. Others could benefit from such a standard being in place. But that's just as far as code readability goes. For maintainability purposes however, I strongly believe that having a standard in place can only have benefits. Sure when deadlines are concerned people tend to think that standards just waste too much time, but that's usually because they didn't know what I've shared with you right here. When it comes to deadlines, there's one thing you need to think about. Do you want to spend a day creating a better standard or delay your release 3 or 4 weeks because you are lost in 1000s of lines code somewhere thinking (maybe I should have created a standard)? That answer is simple to me, isn't it to you? Until I write again, feel free to email me with comments or questions. Happy coding.

Stéphane Richard