8

This is referring to a discussion in an answer and the comments of this question: What's with the aversion to documentation in the industry?. The answer claimed that "code can't lie" and thus should be the go-to location instead of documentation. Several comments pointed out that "code can lie". There is truth on both sides, at least partly because of how poorly and inappropriately documentation is handled.

Should we be on the lookout for lying code, comparing it against any existing documentation? Or is it usually the best source for what it needs to be doing? If it is agile code, is it less likely to lie, or can that code not lie at all?

Community
  • 1
thursdaysgeek
  • 1,303
  • 8
  • 18
  • 1
    Could you please clarify what you mean by "lie"? We shouldn't have to refer to comments in another question in order to get your context. – user16764 Jun 22 '13 at 21:13
  • @user16764 Without looking at the other thread, the first thing to pop into mind is the [Underhanded C Contest](http://en.wikipedia.org/wiki/Underhanded_C_Contest) – Izkata Jun 23 '13 at 19:04
  • If the documentation says that the code should do foo, and the code does bar, does that mean that bar is what the code should be doing? Or are we assuming that bar is the correct action because we never read the documentation, because the code is always correct? – thursdaysgeek Jun 28 '13 at 22:35
  • If the code has been accepted as bar, then the documentation is wrong and outdated. But if foo and bar are closely related, and the users haven't noticed that it doesn't quite solve their problems as they expected, then perhaps the documentation on foo is not wrong? In other words, is the code _really_ the be-all and end-all of what the code should be doing? – thursdaysgeek Jun 28 '13 at 22:38

4 Answers4

9

In layman's words:

Yes, you should search for lying code and make it tell the truth. But not by comparing it to the documentation. That would be a method for detecting documentation that lies.

There are several ways code can lie, of which I will mention just a few:

  • Blocks of code that never gets run because conditions that are never met. The code is lying you about how much it does.
  • Code that adds unnecessary complexity lies about how complex the problem really is.
  • Code with no naming conventions lies because it misleads you into thinking it does something different to what it's really doing.

The shorter is, the less it lies. It's self evident.

The less complicated the code is, the more transparent it is. So it lies less.

Arcane syntax tricks lie a lot. Prefer clear, step-by-step algorithms. They lie less.

A good static code analysis tool can help you find code that lies.

Also a good automated test battery forces the code into telling the truth.

Tulains Córdova
  • 39,201
  • 12
  • 97
  • 154
  • 4
    `The shorter and terser the code is, the less it lies. It's self evident.` I'd hardly say that. In my experience, the shorter and terser the code, the more opportunities it has to sweep lies under the rug, generally by hiding them in deceptive function calls. – Mason Wheeler Jun 21 '13 at 23:13
  • @MasonWheeler You are right. I edited the "terse" part. – Tulains Córdova Jun 21 '13 at 23:17
  • I'm not convinced by "Code with no naming conventions lies". It's certainly bad, but how can it be lying if it's not telling you anything? "I'm not telling you!" is stubbornly obstructive and uninformative but not deceptive. Surely the "lie" is when a naming convention exists, but is used in a way that doesn't match what the code actually does - for example if you're using Hungarian (yuck!) but occasionally have the prefix `p` for a variable that isn't a pointer. –  Jun 22 '13 at 01:40
  • 2
    Actually, what you're suggesting might be better described as "sophistry" than simply as "lies". Sophistry tends to be verbose and complicated precisely so that it's difficult to see the logical flaws, and is superficially clever and confident so that people are scared to question it in case they look stupid. –  Jun 22 '13 at 01:51
  • Another example: Code that changes underlying language or runtime properties, eg redefining or masking primitive behavior. – JustinC Jun 23 '13 at 17:45
6

Code can't lie.

What is in code is what your program is currently doing - no matter what documentation, QA, or the customer says. Especially if your code has been released and been in the field for a while, that expected behavior should not be ignored.

The code can certainly be incorrect. It can certainly be misleading in its naming or organization. It can certainly be unreadable.

But if you want the source of truth for what your code is doing, not what it's supposed to do, not what it was designed to do, not what you thought it was doing... if you need to know what it's actually doing, go to the code.

Telastyn
  • 108,850
  • 29
  • 239
  • 365
  • There's a school of thought that if you're deliberately deceptive but pedantically correct, then you're not lying. It's not the only school of thought. For example, I have an old edition of [Detecting Lies and Deceit by Aldert Vrij](http://www.amazon.co.uk/Detecting-Lies-Deceit-Implications-Professional/dp/047185316X/ref=sr_1_15?ie=UTF8&qid=1371866233&sr=8-15&keywords=vrij). One of the first things this does is consider various definitions of lying and deception, choosing to include pedantically-correct-but-deliberately-misleading statements partly because that's a common understanding anyway. –  Jun 22 '13 at 02:08
  • Sorry, but saying "but it was pedantically correct" doesn't mean you can't be called a liar - even if people don't argue back, they still know it. –  Jun 22 '13 at 02:09
  • @steve314 - pssh. The original question was around comments. Building a straw man for these rare scenarios where code is misleadingly named in order to argue in favor of commenting (and ignoring the far common scenario of comments being out of date) is absurd. – Telastyn Jun 22 '13 at 02:18
  • 1
    I agree with that - I'm not arguing the point you make, only the apparent definition of "lie" you use while doing it. Code *can* lie - not to the compiler, but certainly to human readers. It's even an intentional goal in some cases - things like the obfuscated C contest would be a relatively benign example. Sophistry, as I suggest in my comment to user61852. Just because a compiler sees through the lie doesn't mean it isn't a lie. –  Jun 22 '13 at 03:16
  • @Telastyn I'm guessing you've never had a filter do a redirect causing a step-through to actually happen on whitespace and then go into code not called from that method, never to return, have you? God I hate the !@#$ Java devs do with Java. – Erik Reppen Jun 22 '13 at 21:32
  • The original question was about documentation, but I'm not convinced if the documentation says the code should do one thing and the code is doing something else, that it is the documentation that is wrong. But perhaps that is still not a lie? – thursdaysgeek Jun 28 '13 at 22:33
0

You ask several questions.

Should we be on the lookout for lying code?

Of course!

Should we be comparing [code] against any existing documentation?

That could never hurt, though as mentioned in other answers, more often than not this will lead you to find problems in the documentation, not in the code.

Or is [code] usually the best source for what it needs to be doing?

It is always the best source for what it is doing. The best source for what code should be doing can be (a combination of) different things though, the main ones being:

  • The code itself;
  • The calling code;
  • Comments in that code;
  • Documentation;
  • Unit tests;
  • Integration and regression tests;
  • The programmer;
  • The end user;

Which is the "best" source (or combination thereof) depends on your situation.

If it is agile code, is it less likely to lie, or can that code not lie at all?

I'm not sure what you mean by "agile code", AFAIK "agile" usually refers to the coding process. Supposing you mean "code created in an agile programming process" then I think it's safe to say that it can still lie. How likely it is to lie, compared to code created in e.g. waterfall style projects is a subjective matter (personally I don't think there's a big connection).

Footnote
All the above is under the assumption that code can lie, and that this is a basic (though bit contrived) example:

public int DivideByTwo(int input) 
{
    return input / 3;
}

This is just one example where I'd say "code lies", @user61852 has a few others (unreachable code, complexity of code not matching complexity of problem, bad naming), and I think there are many more. Wikipedia has a somewhat decent summary of lies, many of them can be found code.

Note that if you're in an argument with someone, be very sure the other person's doesn't mean by "code can't lie" that "code does what it does". In essence the other person here is defining using a definition for "lie" that's so narrow that it can declare the statement "code can't lie" as an axioma / basic truth. In this case it's probably best to agree with his/her axioma.

Jeroen
  • 523
  • 1
  • 6
  • 18
0
if (x > 5) {
  doSomething();
} else {
  doADifferentThing();
}

You can argue about whether the word "lie" is technically appropriate, but this code is implying quite clearly that x will sometimes be greater than 5 and sometimes not. If you look at the full program and discover that this function is ever only called in one place, and that x is always set to a constant 6, then that's a lie.

Moreover, the compiler may have noticed this, and replaced this block of code with simply

doSomething()

If doADifferentThing isn't called anywhere else in your program, it may be removed from the program entirely.

If your language supports an assert of some kind, which is turned off in production builds, each assert statement is potentially a lie. A typecast is another assertion which could be a lie.

Tyler
  • 873
  • 8
  • 16