The Confusion Index

At some point many months after you write you code, you will have to go back and change it. Or someone else will. And then a while later, someone else will change it again.
That someone will be picking their way through your code to find why it is broken, or to find the place to add a new feature.

As they pick their way along, your code may be clear, concise, or it may be misleading and confusing.



Commented out code?
When I am looking through the code for a bug, I find that you have commented out a call to a function. So now I am wondering.... did you comment them out for some sort of debugging and testing, and then forget to uncomment them? Or did you decide they were not needed.
If you decided they were not needed, why not delete them.The source code control system will have the code's history. The commented out function call is now a corpse spreading the contagion of confusion.

Overly detailed comments
There's the hugely detailed comment of exactly how you did something. It was very useful until someone changed the code, and not the comment. Or perhaps the comment is correct, and the code is wrong.
If you had kept to the big picture, then the comment would have remained valid. The function names, the variable names, and the code itself should give me the details. Comments are for ideas and goals, not details.

Orphan functions
There's a function that's not used anywhere, it does not feature in a unit test, and I'm tempted to use it, but since it's an orphan, it may not have been updated when some important change was made elsewhere. Will it work or not?

Unexpected Side Effects
Then there was the function that had access to all the data you needed, and it was a convenient place to do a quick update. Of course now the function does 2 things, and second is not at all obvious from the code. Who would imagine that CountValidItems()would also delete the invalid ones?

In some cases the programmer that made these mistakes was me. But I think I would have to look long and far before I find a programmer who was not guilty of these and more. And each time a little short cut or a liberty is taken, the Confusion Index increases. The code gets harder and harder to follow. And harder to change.
The trade off is pay now, or pay later. Later seems easier. Until Later.