Saturday, June 2, 2007

Cleaner code, better maintainability, less time scratching your head bald!

There are 6 tips that Jeff Vogel, President of Spiderweb Software, shares on how to "keep your code from destroying you". For the full article click here.
  1. Comment Like a Smart Person - this tip seems like the simplest to do, but a lot of us tend to overlook inserting (smart and useful) comments.

    A good example:

    accesstype returntype ExampleFunction(datatype parameter)
    //This line of code accomplishes a specific task (usually 2-3 sentences
    //or maybe less, but you have to be concise and be sure
    //not to miss anything).
    //This function task a parameter needed for the task
    //This function returns the returntype specified.
    [a long list of code]
    //Insert a comment here if you code is too long.
    [more code]

    An example of what NOT to do:

    accesstype returntype ExampleFunction(datatype parameter)
    [a long list of code]
    //Finished ExampleFunction, i hope you understand. *evil laugh*

  2. Use #define a lot. No, a LOT. - This is meant for the C/C++ langauge, but the essence of the tip is to declare constants instead of manually changing the same instances of a certain value.

    A good example:

    #define THE_NEVER_ENDING_PI_CONSTANT = 3.14; or
    const int thePiConstant = 3.14;

    Now let's say you call function that uses the Pi constant.


    Now let's assume you have a thousand calls of that function in your code. If you wanted to add more deciamal places to your Pi definition, you only have to edit the constant. If you didn't have the definition, you would be manually editing the function call a thousand times. You savvy?

  3. Don't use variable names that will mock you. - Another no-brainer tip that we overlook, or feel that we don't need to fix. Following this tip really, REALLY helps code readability! Imagine reading someone's source code and you encounter the variable "i" or a variable named "oneInteger", or "intCircle". Now imagine that you're deep inside a function's loop, or within another procedure/method. You'll stop and wonder, "What does this variable mean again?". Don't laugh, this is true, and I've encountered programmers who do this, A LOT!. Instead give your variables descriptive name like: numberOfCustomers, totalUserCount, and the like.

  4. Do Error Checking. You Make Errors. Yes, You. - Always try to anticipate what users would try to input into your programs. Even if you specifically told them to input integers into textbox, some people STILL input letters no matter hard you try! With this in mind you should alway incorporate some form of error checking, be it the try-catch model or simple filtering of entered data.

  5. Premature Optimization is the root of all evil - Donald Kluth - Don't try to overdo optimization. Some programmers are neat freaks and can't stand looking at cluttered code and even try to optimize it themselves only to realize that the program does not work when they try to build it! It's sometimes better to leave stable code as it is if you are not 100% sure it WILL work when you optimize/edit it. The same thing is true about OOP design. If there is no other way to design code, go for the procedural approach.

  6. Don't be too clever by half - Always go for simple approaches to writing code. A good practice would be to spilt miles of code into smaller modules. This is especially true for methods/functions. Try to limit a function's job to one process per function. An example of this write separate function for getting the area and perimeter of a circle, i.e. two functions: CircleArea and CirclePerimeter. Not GetCircleAreaAndPerimeter. Doing so would greatly improve readability and promotes maintainability.
Jeff Vogel's Conclusion (Really funny!)

At this point, you may be thinking, "Wow. That was a big waste of time. All of this stuff is obvious and everyone knows it. Why did anyone write all of this?" I hope this is what you're thinking. Then you're already smart. Good for you.

But don't think that all of this is obvious to everyone. It's really not. Bad code gets written all the time. But it doesn't have to be that way.

If you are trying to wrangle tons of code and keep it from destroying you, I hope that some of this helps. Keep it simple, keep it clear, and you will save lots of time and screaming.


1 comment:

Dot said...

Interesting to know.