Would you like to take Tick-the-Code out for a spin?

Here are the steps for a successful test drive.

  1. Preparations
  2. Start
  3. 2nd Step
  4. 3rd Gear
  5. 4th Phase
  6. 5th Place
  7. 6th Mile
  8. Finish
Preparations

Low-tech approach works for sure.

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.

Recipe for a successful test drive:

  • 1350g well-rested brains
  • 1 pen (red, green, pink or blue)
  • 1000 lines of printed code (max)
  • 6 rules (2 for warmup)
  • 1 hour of quiet time

Warm the brains up by ticking the code with the warmup rules. Apply the rest of the rules to the code with the pen during the remaining time. Tick until time is up. Enjoy with a pinch of professional pride.

Start

MAGIC: "Do not hardcode values."

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.

MAGIC tick example 1 MAGIC tick example 2 MAGIC tick example 3

Click for examples of MAGIC ticks

2nd Step

ELSE: "An if always has an else."

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.

ELSE tick example 1 ELSE tick example 2 ELSE tick example 3

Click for examples of ELSE ticks

3rd Gear

TAG: "Forbidden: marker comments."

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.

TAG tick example 1 TAG tick example 2 TAG tick example 3

Click for examples of TAG ticks

4th Phase

CLOSURE: "Invalidate pointers and resources after use."

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.

NULL tick example 1 NULL tick example 2

Click for examples of NULL ticks

(NULL has since been upgraded to CLOSURE)

5th Place

PTHESES: "Parenthesize amply."

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 C-based languages and Java are vulnerable to this problem unlike Python. The Python programming language doesn't suffer from this because indenting and white spaces are meaningful in it.

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.

PTHESES tick example 1 PTHESES tick example 2

Click for examples of PTHESES ticks

6th Mile

CALL: "Call subroutines where feasible."

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.

CALL tick example 1 CALL tick example 2

Click for examples of CALL ticks

Finish Line

Collect the results and analyse.

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.

Here are my results on the sample file.

  • Date: 10-Jun-07
  • Time: 34min
  • Code: 596 physical lines
  • MAGIC: 76 (+1)
  • TAG: 7
  • NULL: 8(*)
  • PTHESES: 1
  • CALL: 11
  • ELSE: 24(**)
  • TOTAL: 128 ticks

(*) The NULL rule has since been upgraded to CLOSURE.

(**) I checked the rule ELSE last, unlike the instructions state.

Last updated: 16-Aug-09.