Tick-the-Code Code Examples
| MAGIC ticks |
|---|
Even zeroes, even initialization values contain magic.
Regardless of context, strings of characters need to be ticked for further analysis. Think about the effort to translate a module that has its strings sprinkled all over the place. It's also much easier to check for consistency if strings are collected in one place. Consistency is vital for various debug strings.
Here's an excellent example of the swarming behaviour of magic numbers. These numbers probably have many relations to other numbers in the nearby code. The fact remains that code needs to change. How easy is it to change this kind of code without breaking it?
The rule applies to ALL literal numbers, character constants and also strings. Instead of using a constant value out of thin air, you should more often than not name the value in a creative and meaningful way. You use the rule to find out where the magical constants reside. You leave it up to the author to take the ticks seriously and act accordingly.
|
| ELSE ticks |
Here's quite a clear one ELSE violation. Perhaps there is nothing to do if the boolean expression is false, but the code keeps that as a secret. Whoever maintains this code needs to assume that the code is correct. We all know that is not always the case.
This is a particularly nasty pair of ELSE violation. There's clearly something wrong with the indentation. The second if is clearly indented as if it belonged inside the upper if block. However, there are no curly braces around any block to show that. If this code had been checked with the PTHESES rule, here would be two violations.
No doubt about it, there is no code in the else branch. Is that accidental or on purpose? There's no way to tell for sure. We can try to deduce it from the surrounding code and hopefully we find a relevant and up-to-date comment that mentions the missing pieces not being needed. Otherwise, we're out of luck.
It would be so easy to record the thought "Here we don't need any code if the boolean expression is untrue." Just a comment /* no else */ would explicitly tell the reader that the else branch was considered and found unnecessary. If we'd follow this habit, we'd only need to suspect those if statements that don't have an else branch or a noelse comment.
|
| TAG ticks |
This TAG violation is simple to find, the "XXX" is a clear giveaway of a marker comment. It just begs for attention.
A comment phrased as a question is shouting "UNCERTAINTY"! Is the code correct or isn't it? Is the code finished or isn't it? Here's a potentially dangerous spot right here.
"Hard-coded for now"? "For now"? When will it be changed? Before the production release? Before the year is out? Yesterday?
Source code has no place for uncertainty. The worst developers can be experts in hiding their uncertainty, which is an expertly BAD thing. The ones sometimes lacking in skill, yet honest developers write their concerns in comments. These are excellent clues to spotting uncertainty and error-prone code.
If you tick more code, you'll bump into comments talking about certain compiler versions or mentioning other tool or environmental peculiarities. If the code is old enough, the comments might refer to ancient problems. Their time might have passed by now. Use TAG ticks to analyse these comments and perhaps get rid of ancient crud.
|
| NULL ticks |
You might recognize this example from the ELSE violations. Very often ticks like to form groups. It is important to tick each rule violation separately and clearly name each tick with the appropriate rule name. Unless you have ticked a concern, you shouldn't expect it to disappear from the code.
'Release' is a good keyword to look for when you are looking for NULL violations. It usually means that something has come to an end. The pointers possibly pointing to whatever it is that is released might need to be invalidated so nobody uses them accidentally.
Nowadays the rule CLOSURE has replaced the NULL rule. While NULL was only concerned with invalidating pointers after use, CLOSURE applies more generally to any kind of ending. It can be anything from closing a file, or freeing dynamic memory to disconnecting from a database or closing a socket.
|
| PTHESES ticks |
Multiple arithmetic operations are a breeding ground of bugs. Using parentheses to explicitly state the intended order of calculation can only make the code clearer. This is especially important if we imagine the code being just about to be changed and somebody needs to add for example "+ 1" to the equation.
First of all, we have some magic numbers in this code (the rule names aren't visible, only the purple circles). But there are also various operators in the mix: "&", "<<" and even some parentheses. But I claim there's still some missing. You could of course take a look in the operator precedence table, but why bother? Why not just make it explicit even if the right order was already supported by operator precedence? What do you have to lose? Just a bug or two, I say.
According to dictionary, the word 'explicit' means "to state clearly and in detail, leaving no room for confusion or doubt." That's what source code needs to be like. Explicit. Source code must state everything clearly and in detail, leaving no room for confusion or doubt.
|
| CALL ticks |
These two lines seemed to belong together. In many places in the example source code, they were either both changed or read at the same time. One way to make sure both of the variables are always set or read, is to package them in a routine.
Handling a mutex seems fairly clear, but it is anyway six lines of code. In the code example, the same six lines actually were repeated in many a place. The locking of a mutex is supposed to help make the code work, but you don't always need to see all the details. Make a routine to hide the details and you get to concentrate on the task at hand.
Interpreting the CALL ticks isn't always as straightforward as the examples make it out to be. Sometimes you need to think about the abstractions in a larger sense and one CALL violation might cause a massive reorganization of the architecture. If you notice that the abstractions in the code are all wrong, don't blame the CALL rule, it is just raising your consciousness to notice the flaws in the design. You need to take better care of the design with ot without CALL.
|
Last updated: 19-Dec-08.
Tick-the-Code in Action:
Click for a video on MAGIC.
Get your bearings:
Click for the sitemap.
Participants comment:
Click for training course details.
