As your programs get more complex and advanced, the necessity for order comes urgently. Classifying the whole code into sections according to topic and purpose is essential to maintain it debuggable; let alone getting drowned in the code. This is why starting off from a code template is a good idea.
The following sections will guide you for a better understanding on how to separate the code in useful ways. At the end, you can download the code template file. It can serve you in any Integrated Development Environment, such as MPLab X or MikroC.
Table of Contents
What is the Code Template?
It's a time saver. Let's start by saying this loud. But it gives also an order which simplifies the code for current and future projects. Since you can expect where every section is located. In other words, is a guide to write code.
How does the Code Template looks like?
When you start a new project with the code template, the variables, aliases and other elements are found quicker. The following 2 examples suggests that writing without any kind of template, will result in a long term headache that escalates with the size of the code.
int g2;
void gg20 {
while(x<100){
PORTB.B0=1;
x=g2+25;
if (0x40==0) break;
}
}Example of an unorganized, unreadable and undefined Code.
//Global Variables
int g2; //global variable of ADC value
//Aliases
sbit LED at PORTB.B0; //An alias to do...
#define LOCKOUT 0x40 //An alias to do...
#define hoursWork 25 //An alias to do...
//Functions
//Function that does 'x'
void gg20 {
while(x<100){ //Infinite loop that checks 'y'
LED=1; //Write a '1' to pin
x=g2+hoursWork; //Add value to the counter
if (LOCKOUT==0) break; //Check the status at the register LOCKOUT
}
}Example of an organized, readable and defined code.
You can see other examples of unorganized code in this post “Blinking LED with a PIC microcontroller, a helpful Indicator“.
Sections of the Code Template
This code template gives you a few ideas how to organize your code and where to locate the variables, functions, aliases and much more. It's organized with commentary lines where everything should be placed.
Name, date, version and information
Yes, you should name your project and everything it does.
- Is the code written for a university project or for an industry?
- Which date was this code started and when was it last modified?
- What does the code execute?
Be descriptive because you may be reading this after months. You may not remember what was on your mind at that time.
/*-----------------------------------------------------------------------
techZorro University
Microcontrollers Faculty
Code Template
Name: Example.
Author: Juditova.
Version: 1.0.
Creation: 22-IV-1970.
Revision: 22-IV-2021.
Description: ...
---------------------------------------------------------------------*/Bits, pins, alias and constants
Giving a easy-to-remember name to ports of the microcontroller, constant numbers or register addresses can simplify your coding work substantially. Forget about memorizing machine-oriented names and give a human-readable name. Place all of them inside one section.
Here is a example of code. Instead of writing ‘0x40‘ just write ‘LOCKOUT‘ and the compiler will know what are you talking about. Instead of writing the port PORT.b0, refer to it as ‘Int_FreReg‘ or any name which is easy to remember for you.
/*------------------------------------------------------------------- 1. DEFINITION OF BITS, PINS, ALIASES, CONSTANTS ---------------------------------------------------------------------*/ #define LOCKOUT 0x40 #define pi 3.14159 #define baudios 9600 sbit PWM_ACEL at PORTC.B2; sbit INT_FREREG at PORTB.B0;
Do you start to see why a code template is important?
Global variables
Locate the variables that can be accessed from anywhere in the code in one convenient section. This way you refer to them quickly because you know where all of them are.
/*------------------------------------------------------------------- 2. DEFINITION OF GLOBAL VARIABLES ---------------------------------------------------------------------*/ unsigned int varA; unsigned char varB=0;
Function prototypes
It's better to declare the functions before calling them in the first place. What do you have to do? Just leave them outside the main, as you would normally do, but add a semicolon at the end.
/*------------------------------------------------------------------- 3. FUNCTIONS PROTOTYPE ---------------------------------------------------------------------*/ void turnLED (boolean A); int ADC (unsigned char port);
Functions of Interruptions
Hardware interruptions require that you declare the function (the place to go where the flag has been raised) in order to take the action. So why not put all the functions of interruptions in one convenient place? First, declare the function prototypes and then group together the functions.
In my opinion, the most important reason to have a code template implemented.
/*------------------------------------------------------------------- 4. DEFINITION OF INTERRUPTION FUNCTIONS AND ASOCIATED SUBROUTINES ---------------------------------------------------------------------*/ void interrupt (void);
Functions used by the ‘Main'
When reutilizing code, it's better to create functions that can be used again and again. But where do you locate these functions? Let's create the last section of the program where every functions ins neatly organized by a title (is not necessary to place them in order). How? Just add a comment to create the section and give it a nice title.
/*------------------------------------------------------------------- 5. DEFINITION OF THE FUNCTIONS USED BY 'MAIN' ---------------------------------------------------------------------*/
Afterwards, for every function create new subsequent function.
/*-------------------------------------------------------------------
x.1 Peripheral Configuration Subroutine
---------------------------------------------------------------------*/
void Config(){
//function here
}
/*-------------------------------------------------------------------
x.2 UART Write Subroutine
---------------------------------------------------------------------*/
void TextUART(const char *puntero) {
//function here
}‘Main'
Well, this is it! As the name suggests, it contains the function where the program starts executing code. This doesn't mean that all the code is written here.
/*-------------------------------------------------------------------
6. DEFINITION OF THE MAIN
---------------------------------------------------------------------*/
void main() {
Config();
while(1){
//code goes here
}
}Although some code doesn't require to be in the Main function in order to be executed, such as interruptions, the Main function remains the origin from where the other functions start.
Order of the Definitions in the Code Template
Did you noticed that ‘Main' function was placed intentionally at the end? Why not at the start if this is where the program starts? Due to the compiler, it may ignore or not recognize the function if there are not describe it before it reaches the Main.
If you require to create additional sections of subsections, feel free to add a commentary line(s). Be descriptive about its use.
Download the Code Template
If you would like to see and read the whole code through, enter your name and e-mail in the form below to download the project. I promise that I won't send you spam; just relevant content to the blog. If you don't see any form below, please click here.
techZorro's Index of Content
Keep Reading!
- 008 – Variable Frequency Drives: how this controller can transform induction motors forever
AC induction motors can be transformed into a highly controllable machine with Variable Frequency Drives or VFD. Click here to listen. - 006 – Regenerative Braking, an awesome Feature found in Electric MotorsThis episode is related to this hidden feature of electric motors called regenerative braking. Click here to listen.
- 005 – 7 types of Electric Motors that you should know aboutThere are several types of electric motors that differs in efficiency, power, cost, torque output, etc. Click here to listen.
- 004 – AC Voltages, Frequencies and Plugs around the WorldLet's talk about electricity! Specifically about how the standards around the world. Click here to listen.
- 002 – RISC vs CISC, how a few Differences are crucial to ComputingToday in the market is found two kinds of processor architectures: RISC and CISC. Both have some advantages. Click here to listen.