# HOW TO DEVELOP
IN AN EFFICIENT AND SAFE WAY

By TuO / SkyTecH
Article from Hugi #17
With permission of the author

Introduction

Many demo coders don't think to the way they are coding. They just consider the result. But now demos are being more complex, the source code is know really complex, and huge. This is why you should be careful when you write some code. It is true for all languages, C, ASM, Pascal, Cobol, or everything you can think about.

Of course there's not a "miracle way" to write understandable code. There's just some tricks it's good to know when you're a brand new coder. This article deals with a second problem, which is really close to the first (even if it is not obvious) : the source safety. What do I mean? Just one simple thing : never hang computer. There's simple tricks to avoid hanging computer, which means reboot, and more time wasted.

What's that fuck? I can read my sources!

Yeah, while you are updating a part of you new mega powerful top speed extra funny 3D engine, you can remember all subtilities of the sources. But what after 1, 2, 6 months? If your code is not properly written, it's just hours wasted trying to understand why the hell you're doing this here instead of there!

What you should keep in mind when you write some code, it's that it won't be easy to read it if there's no explanation at all. There's two ways to make code understandable :
- use self-explained variable names
- comment the code

- Self-explained variables

  When you use variables (really often in high level languages) you should try to give them a name that tell what the hell you are doing with it. Then, later when you'll read again this part of sources, it'll be easy to remember what each variable is supposed to do.

  Some examples : don't use "o" for an object. Try to use "Object", "object", or something like that. Don't use "c" for a camera, "p" for a pointer to somewhere in memory, etc.

  For more complex things, don't hesitate to make complex variable names, with use of case or "_". Some examples : CreateCamera, LoadFile, DrawScreen, reload_text, erase_buffer, etc. The typo is up to you. But when you choose one, you should try to keep the same in all your program. It makes it easier to read.

  More things to type off? No problem, do you know copy/paste ? In all good text editors since many many years.

  Note : there's some common exceptions to this rule : every coder know the "i" variable. It may look a really not self-explained name, but in fact it is. "i" states for "integer", that is the "int" type in C/C++. There's of course all derivated : "c" for a character, and so on. These are acceptable. BUT you should NEVER make these variables global. It is a really good way to have bugs or things like that.

- Comment the code

  Put some comments in your source code is always a pretty good idea. You should write some words before your function to explain what it is supposed to do, what it takes for argument, and more.

  Inside the function, just put comments where it is needed : between logical parts, before some large value computing, etc. The comments should explain what is going on.

- A small example :

  Here is a small C example :

  -> What you shouldn't do :

         #include <stdio.h>

         int i;

         int fct(int a, int b)
         {
           return a*b;
         }

         void main(void)
         {
           for (i=0;i<10;i++)
             printf("2*%d=%d\n",fct(2,i));
         }

  -> What you should do instead :

        /*
         * A simple program to display the table of multiplication of 2.
         */
        #include <stdio.h>

        /*
         * The multiplication function
         * Returns Value1*Value2
         */
        int DoMul(int Value1, int Value2)
        {
          /* Just return the value of multiplication */
          return (Value1*Value2);
        }
        /*
         * Main function
         */
        void main(void)
        {
          int i;
          /* Process the 10 first values */
          for (i=0;i<10;i++)
            printf("2*%d=%d\n",fct(2,i));
        }

Hey my progs never hangs (or not often)!

Hum there's a lot of programs or demos that hang for a totally unknown reason. In fact, there's often a simple explanation to give. And some simple rulez could make it easier not to hang (or hang really less).

One important thing to do is to check arguments in a function, and react accordingly. If you expect a pointer from the user (even if the user is you!), then be sure to check that pointer is not NULL. Maybe it is a non valid pointer, but hey then you can't do anything. If you expect a value from the user that must be in a given range, be sure to check the value against this range, or you can have problems. (tip : often ranges are 256 or 65536, so use BYTES or WORDS values to store them, and you'll be sure the value is in the range).

If you are sure the values you are working with are correct, there's no more reason to hang, except if you are doing something really stupid :)

Another thing : never forget to handle possible errors. An unhandled error can cause a crash later in the program, and it is often hard to find the real reasons of this kind of crash.

And finally, try to always reset variables when you are allocating them, or freeing them. The best should be to reset a variable you used to its former state to avoid all possible hang later, but it is often not useful.

Ending

I personnaly apply these rules (the "never hang" rule since not so much time :) and I think it's great. I'm working on my new 3D engine since 6 month now, and even after 5 month I didn't read my assembly sources for point transformation, I still understand it because of all comments I put in (note that it is a full ASM FPU function, with a lot of stack operations, so it could be a bit confused if not commented). And I made a 3DSmax plugin with this 3D engine. I hanged my computer only once, and it was just because I made a stupid mistake! Not all my 3D engine is secured yet, and this is why I have some problems. But when I experiment problems, I add security where the engine crashed, it allow me to found the problem, and everything goes well!

I really hope this piece of text will help beginners to learn faster the marvelous world of programmation, and that all coders that had problems with misterious hangs will apply these rules and finally find all their bugs!

TuO / SkyTecH