Tick-the-Code Test Drive

Print out some code. A thousand physical lines (including empty lines etc.) will do fine. If you know the 'C' programming language, you can print out this Open Source file sample (<20kB). (The file uses Unix-style newlines (LF).) Once you've test-driven (or test-ticked) it, you can compare your results to mine. They should roughly match.

Take a bright colored pen (non-black, I mean). Reserve an hour of uninterrupted time. Find a quiet place to retreat to, if your desk is noisy. Protect your quality time and commitment. Silence your mobile phones and pagers, ignore any incoming emails, text messages or any other distractions. Hide from personal interrupts. It's only for an hour. Anybody can be unavailable for an hour.

Now you are ready to proceed.

Take the next rule seriously. As checker, do not question any of the rules. No matter how simple the rule feels, check it manually. Even if you could make a script, don't. This simple rule is there to get you to relax.

Promise me you're not going to question the rule. Just do it. Promise me!

The MAGIC rule says the code is not allowed to include hard-coded values. It means that you, as checker, need to circle (with your bright colored pen) any literal number (42), character constant ('b') or string ("characters") in the middle of the code and tick it with the word "MAGIC". When you find one, tick it and move on to the next one. Don't stop to wonder. Don't even think about how you'd "fix" it. It shouldn't take many seconds to find a number and tick it. Move as fast as you can, without missing any rule violations.

Tick zeros (0) and ones (1), regardless of their context. Yes, even in a for loop.

Do tick plain numbers as array indices (array[4]).

Don't tick NULL, it is not a hardcoded value.

Don't tick #define or const values, they have names already.

Don't assume you need to do something to the ticks. Don't worry about that yet. You will tick places, which will not be changed. But you will be ticking fast.

Once you've gone through the whole code, ticking every violation, count them and write the result on the cover page of your source code (MAGIC: 55). Record the time, too (in minutes). Note any questions or comments that might have arisen during this phase.

The rationale behind this rule is that numbers and other values magicked out of thin air are the scourge of software maintenance. In addition, the relationships between the values are often completely missing from the code. That is sure to cause at least wasted time, as a maintenance engineer tries to figure out how to change the code correctly.

The second rule is called ELSE. Look for all if statements that are missing their else branch. In other words, find the first if statement and check if it has an else branch. If it doesn't have one (or a comment about not needing one), circle the word if (which is there) with a nice colorful circle and write next to it, as close as you can, with readable handwriting, the name of the rule "ELSE". Then find the next if statement. You don't have to do anything else. Try and locate every missing else branch.

An if-else-if structure must end with an else, otherwise it violates the rule and you'll tick it.

The rationale behind this rule is that a forgotten else branch can be a dangerous hole in the logic. Even if the syntax of the programming language doesn't require else branches and even though in many cases an else is unnecessary, it makes maintenance that much harder, because both unnecessary and forgotten else branches look alike.

As a general guideline, whenever you're feeling unsure about ticking something, do. The uncertainty means that you must make certain that everything is fine, so you must tick the code.

The next rule is called TAG. A tag is normally attached to, for example, a suitcase or a toe. Some comments are like tags, like markers pointing out unfinished business in the code. The rule forbids the use of such comments. Unfinished code poses a threat. There is a real danger of forgetting to finish the unfinished. Sometimes marker comments point to forgotten things, which are always problematic in the digital world, where absolute accuracy is demanded.

A marker comment calls you to it to finish the job. The simplest marker comments say TODO, FIXME, XXX, HACK or include the username or something else that's easy to find. The more difficult ones only hint at unfinished business by ending in a question mark (?) or an ellipsis (...). Read through each and every comment and tick the ones that point to unfinished code or are otherwise uncertain. Maybe the time has come to finish the business.

Some comments might talk about workarounds for a certain compiler model. We tick such comments, because they might be old and outdated. The time might have come to get rid of such workarounds.

The next rule is called CLOSURE. When you free dynamic memory (free()), the pointer that you got when you reserved the block (malloc()) still points to the freed block. It looks quite normal and usable, but if somebody were to use it, problems would follow.

Look for locations where a pointer should be set to NULL, in other words, invalidated. This rule makes sure that invalid pointers are invalidated so that the inadvertent use of invalid (dangling) pointers can be caught elsewhere.

This rule applies also to similar situations, i.e. where a pointer, a reference, an object, a handle or anything else is no longer usable. Databases, sockets and file handling contain functional open and close pairs, after which the pointer or handle should be invalidated in one way or another.

Look for places in code which need more parentheses. The rule called PTHESES applies as well to (curly) braces, parentheses and brackets.

For example, if a complicated calculation requires you to recall the table of operator precedence in order to understand the order of calculation, it contains too few parentheses.

Check especially well macros, they often lack parentheses.

The if condition should always be followed by a block of code in braces, even if the code only consists of one line.

The rationale behind the one-liner if braces is that changing code with braces is less error-prone than without. Without the braces around the block, there is a slight danger of just indenting the added code line so that it looks to be inside the if-then block, but isn't.

/* original */            /* incorrect change */      /* correct change */
if('expression')          if('expression')            if('expression'){
    just_one();      =>       just_one();                 just_one();
                              yet_another_one();          yet_another_one();
                                                      }

The rule doesn't say where to place the braces or parentheses. That is a matter of style and there are no wrong answers in matters of style, only various opinions.

The rule is called CALL. Your task is to look for blocks of code that could be their own function or method but aren't. You can find them best in large functions or methods. Circle the whole block, which clearly has a purpose and would make a good subroutine.

Modularity is along with comments an important theme in Tick-the-Code. In the complete rule set, there are four modularity rules and four comment related rules. Although most big design decisions have been done in the architecture phase (what architecture phase?), the game is not completely lost even in the coding phase. There are ways to make huge functions into smaller, more manageable one-task routines. Little by little, even large systems can be made more maintainable. Assuming we have enough time. That's why you should do this again next week. With small, but regular efforts you can go through a huge system thoroughly and without disruption of your normal duties.

Now you've gone through the source code six times. Count the sum of the individual rule violations to get the total number of ticks. Record the total time next to it on the cover page.

If you used real code, take the code to whoever maintains it and ask them to take a look at your findings. IMPORTANT: make it clear to them that they are entitled to ignore any tick, even all of them. They don't have to do anything if they don't think it will help. However, there are important principles behind every rule and any tick could point to a possible vulnerability in the source code. A tick is a possible improvement, so they shouldn't just ignore everything without looking.

Send your comments and questions to testdrive@tick-the-code.com. If you submit detailed information about your ticking session (tick counts per rule with times, the amount of code, the programming language), I will send you the full set of Tick-the-Code rule cards. Just remember to include your postal address in your email.

If you used the sample source code, you can now compare your results with mine on the right. They should roughly match.

If this test drive made you interested in learning more, ask for an offer on a Tick-the-Code training at your company or in your city.