# The anatomy of a C code source file

Structured programming language

For any computer or microcontroller, a program is a set of instructions to be executed. C is a structured programming language. This means that the set of instructions have to be ordered in a certain way in order to be properly executed. For example, if we want to write a simple program which multiplies two numbers, first we define the numbers (e.g. a = 2, b= 4), second we multiply them (e.g. a*b). This means that the instruction to read the numbers come before the instruction to multiply them.

Programming language syntax

Every programming language comes with it’s own syntax. When we write a source code we have to make sure that the syntax is fulfilled, otherwise the source code will not be able to be compiled. Syntax is the collection of rules regarding typography (keywords, letters, special characters, numerals, etc.) and the use of punctuation marks. For example, in C, it’s not allowed to use the name printf for a variable since printf() is already a function name. If we still use function’s name for a variable, the compiler will throw an error.

For this tutorial we are going to use a simple program which calculates the trigonometric function of an argument:

$y(x)=sin(x), \hspace{5mm} x=\frac{3 \cdot \pi}{2}$

The source code for our example:

/*
Author: Ynot Krats
Version: 1.0
Date: 20.12.2016

Description:
This code is calculating the function
y(x) = sin(x)
*/

#include<stdio.h>
#include<math.h>
#define PI 3.1416

int main(void)

{
float x, y;

x = 3*PI/2; // in radians, equal to 270 degrees
y = sinf(x);
printf("sine of %.3f radians is %.1f\n", x, y);

return 0;
}

A very good programming practice is the use of comments in order to document properly what the code is doing. Comments are only used to describe the purpose of specific parts of the source code, they are not part of the instruction set which will be run on the machine (computer, microcontroller).

A good practice is to write a comment at very beginning of the source code, describing the author/developer, the version of the file and the date when it was created. This way, if several developers are working on the same source code, it’s easy to track down the changes in the project.

There are two type of comments, multi-line comments and single line comments. As the name suggests, multi-line comments can be split in several lines. The beginning of the comment starts with the character sequence /* and it ends with */. Example of multi-line comment:

/*
 Author: Ynot Krats
 Version: 1.0
 Date: 20.12.2016

Description:
 This code is calculating the function
 y(x) = sin(x)
 */

Single line comments are only limited on one line. They are usually used for shorter description of the source code. A single line comment starts with the sequence of characters //. There is no closing sequence since everything after // is considered comment. Example of single line comment:

// in radians, equal to 270 degrees

Bear in mind that everything between /* and */ on single or multiple lines, and after // on the same line, will be ignored by the compiler since they are interpreted as comments.

Preprocessing, compiler directives

Before the compiler starts to compile the source code, the preprocessor searches all the compiler directives marked by the # (hash) key. There are several types of compiler directives, in our example we use only two types:

#include<stdio.h>
 #include<math.h>

These are include statements, which are instructions for the preprocessor to replace the directive line in the code with the content of the header file (*.h). #include<stdio.h> means: replace this line with the content of the header file stdio.h.

The files with *.h extension are called header files or include files. There are two types of header files. Standard header files, which come together with the development environment, and custom header files, which are created by the developer. Both types are text files, readable by humans. The standard header files are located into a special directory named Include Directory. The main purpose of standard header files is to point to the definition of library routines (defined functions) in order to be used by the developer.

For example the function printf() displays data on the command prompt (console). In order to use it we need to include the library which point to it. This is achieved using the directive #include<stdio.h>.

The same applies to the mathematical functions. Most of them are defined in a library, so in order to use the we need to include the header file. Thus, in order to use the main trigonometric functions we need to include the math library with the directive #include<stdio.h>.

If we don’t include the relevant header files for the functions we use, the compiler will throw an error since it can not find the definition for the functions.

We are also using a #define directive. With this directive we can define variables, symbols which are going to be common through all the source code. #define PI 3.1416 means that the preprocessor will replace everywhere in the source code the keyword PI with the value 3.1416.

Functions

A C program (source code) is a collection of functions and variables. A function is a collection of instructions (statements) to be executed by the machine. Variables are used to store values during program execution. A function in C is equivalent with a procedure in Pascal or a routine in Fortran.

A special function in C is the main() function. Every program written in C must contain the main() function. When the program is launched in execution, the main() function is run first. Any other function can have whatever name (in conformity with syntax) except the main() function which must keep the name as it is. The main() function can call other functions but other functions can not call the main() function, since it’s executed first.

The template of the main() function is:

int main(void)

{

/* function body */

return 0;

}

The main() function is defined as type integer, that’s why has the int keyword as a prefix. void is also a keyword and it means that the main() function doesn’t expect any arguments. The content of the main() function is defined between two curly brackets: { and }. Everything between these brackets represents the source code of the C program.

For better readability, the main() function is split on multiple lines, but it could be also written as:

int main(void) { /* function body */ return 0;}

the result being the same.

For our example, the body on the main() function contains two variables declarations and three instructions:

float x, y;

x = 3*PI/2; // in radians, equal to 270 degrees
 y = sinf(x);
 printf("sine of %.3f radians is %.1f\n", x, y);

Our code is using two variables x and y both of type float. In C programming language it’s critical to declare every variable, before using it. Otherwise the compilation process will fail because the compiler will not know what’s the data type (integer, float, string, etc.) of the used variables.

First instruction x = 3*PI/2; calculates the value of the variable x. A line comment is added after the instruction for a better understanding of the value of x, 3π/2 radians equals 270°.

The second instruction y = sinf(x); calls the trigonometric function sinf(). This function calculates the sine for an argument of type float and returns a result of type float. The output of the sinf() function is allocated to the variable y.

The third instruction printf("sine of %.3f radians is %.1f\n", x, y); prints on the console (Windows) or terminal (Linux) a string containing the result of the function for that particular argument.

Image: Console program output (Windows)

Notice that both variable definitions and the instructions are terminated with a semicolon (;). Most of the C code instructions need to be terminated with a semicolon. These are needed so that the compiler knows where one statement (instruction) ends and the next one begins. It’s a bit difficult to define in a comprehensive manner when a semicolon is needed, the general rule being: use a semicolon (;) after every instruction within a function’s body, between curly brackets/braces { and }.

The body of the main() function is terminated with the statement return 0;. Since our main() function is of type int, it must return an integer value. By returning 0 back to the main calling program (the operating systems in case of computers) indicates that the program has reached the end without any errors.

In the picture below you can find a summary of a C code anatomy:

Image: The anatomy of a C code source file (click on image for higher resolution)

Test your knowledge regarding The anatomy of a C code source file by taking the quiz below:

QUIZ! (click to open)

For any questions or observations regarding this tutorial please use the comment form below.

Don’t forget to Like, Share and Subscribe!