}

Linux Coding style for coding in C

Created:

Introduction

Almost any lenguage has a style of coding. When you read code of someone else, you will know if that code was written with style. Style is more than giving good names to variables, you know that the code has style when you know what is going to happen next. Learning to write code with style will take you time and you must know that every lenguage has it own style. You can have the best Python style, but if you never coded in Java you will lack the skill to write styled Java code.

Having style is not something for the elite, you must have that skill and if you have it people will love you. remember that good general coding practices is a must have to write good styles.

This tutorial is to give you an idea about C style coding for Linux.

Style guide 1: Write comments

Writing comments to your code is fundamental, specially on "dark side" code. Remember after some months you could be the one reading the code! Try to avoid writing redundant comments. Make sure all tricky parts (that should not exists but we have limited time) are commented. When you write comments you need to think as you are the one who reads the code for the first time, write use cases or how/why the function is called. Another tip for writing comments is to read the code again one day after you wrote it, and then add more comments.

The general rules regarding formatting are:

  • One instruction per line
  • Choose your tab width and be
  • Be consistent with tab width consistent with it,
  • Follow the project guidelines

Choose an editor that fits you

One of the most important things for you is the editor, it the tool that you will use every day. Some people could hate vim or love it, some people love to use eclipse. Make sure you try them and choose the one you liked more. The editor should help you by finding syntax errors, execute tests, compile the code, etc. Choosing an editor is very subjetive and you will find many opinions on each.

Variable naming

Make sure you read the lenguage convention on variable naming. For C the convention is the next one:

  • A variable name can have letters (both uppercase and lowercase letters), digits and underscore only.
  • The first letter of a variable should be either a letter or an underscore. However, it is discouraged to start variable name with an underscore. It is because variable name that starts with an underscore can conflict with system name and may cause error.
  • There is no rule on how long a variable can be. However, only the first 31 characters of a variable are checked by the compiler. So, the first 31 letters of two variables in a program should be different.

The name of the variable should help the reader of the code yo understand the contents of it. Since C is strongly typed langue, you should avoid using the type in the name since the type of the variable cannot be changed. Having good variable names could help you to reduce the explanation on the comments.

GNU-specific guidelines

If you are planning to write code for the GNU ecosystem, you must follow the GNU guidelines. However it is a good idea to read the guidelines to learn GNU style. We will make a summary of the most important guidelines.

use a prototype declaration before main()

if you have your own functions, use a prototype declaration before main(), then define the function when needed

Example

    #include <stdio.h>

    int func (int, int)

    int main() 

    [...]

    int func (int x, int z)

    [...]

Use proper and constant indentation. An experienced programmer will have to see indentation problems. Remember that you must have your editor configured correctly. Sometimes you see the code and it seems to be ok, but the identation could be wrong. Make sure to check edtior identation configuration.

The recommended C code indentation, set at two spaces and braces on a line for themselves.

# Malloc good practices

When writing programs you need to allocate memory and have more control over the memory, there's malloc() for dynamic allocation. Malloc will allocate memory from the head and your program will use the pointer returned by malloc. Always write meaningful error messages, not like the ones operating systems. Make sure you check that malloc() always return zero. Remember always to free your memory!

Use common arguments names for command line program

If you have every used GNU/Linux you will know that most of the program have a --version and --help arguments, and soetimes -v for verbose. Try to use this common names and to implement them.

Documentation

At least you must add a README at the root of your program. It's very recommended to write some documentation in form of manual pages. The README should be something short with most common use cases and a description of what the program does. Every good programmer writes good documentation.

Portability

You software should be portable between unix systems, you should:

  • Avoid ifdefs
  • Avoid assumptions regarding file locations
  • Don't assume endianess
  • Don't assume anything about the CPU

There are more things to have in mind when writing portable code, you will learn them while you try to build software. The most important thing is that your software should be easy to fix when you find a portability bug.

Subjetive styles

Sometimes in C there are "styles" that programmers don't agree. In this section we will review some of them.

Open brackets and enters

This is a common discussion (a benign one I hope) on how to use the bracket. See the next two C code examples

     **while** (var ==  1) {
      code...
    }

Some programmers like to use one enter for the brackets like in this example:

     **while** (var ==  1)
    {
      code...
    }

This also applies to conditional expressions, functions and every occasion where you need to use braces in C code. How much of this you respect depends solely on your taste and stance on the issue.

Spaces on parameters

This is another topic that some programmers argue about. Should you leave spaces between parameters in a function? After the function name? In some programming languages you have to follow some standard, in C this is very subjetive.

    int func (var1, var2);

    int func(var1,var2);

Nested ifs?

Some prorammers don't use nested if, other can't avoid using them. In the process of learning you will build you own opinion about nested ifs, like when to use them, how to make them readable, mainteneable, etc. As always, if you use nested ifs remember to use comments!

Conclusion

Next time we'll continue from where we left off here: going from idea to a complete program, with Makefiles, documentation, release cycles and all the fun stuff. The only exercise I have for you is to skim through the GNU coding standards and modify your code as to conform. And get ready, next time it's fun time!