In some recent discussions I have been shocked to realize that many developers treat DEBB as gospel. This is a terrible idea. DEBB is written by people like me and I am a moron.

The Definition Of D.E.B.B.

In the original version of this article my use of the term “documentation” was not interpreted in the way I had intended. That original article offended a great number of people and for that I am truly sorry. It was not my intention in any way, shape or form. The goal of this blog is not to kick sand on anyone else’s shoes but to share information and to help educate. That does not mean I will suddenly become politically correct (that would be bad for my health) but it does mean that I am not setting out to piss on anybody.

Within this article we are going to use a new acronym; DEBB. DEBB is not just class documentation but encompasses all of the normal sources we use when trying to understand an API. DEBB stands for Documentation, Examples, Blogs and Books. There is no one word that properly encompasses all of those sources. Therefore I am using a new acronym. Feel free to share it.

I Am A Moron

I think that this declaration requires some explanation before we continue with the primary focus of this article. Just like most of the people who read this blog, I write code for a living. Even when I am writing code by myself, there are actually three people working with that code.

First, there is me. I am a clever and talented programmer. I know to keep my code clean and easy to read. I try to do things the right way and I know that if old code is wrong that I am better off fixing it now then trying to code around it.

Second, there is past me. This guy is a fracking moron. He pisses me off on a daily basis as I am having to constant re-write his code. He is generally clueless and causes me more headaches than anyone else.

Finally there is the future me. This guy is smarter than I am, has seen more than I have and has done more. My goal, in addition to making sure my code works, is to make sure that my intentions are clear for him so that I don’t piss him off too badly.

When I claim to be a moron, it is a matter of perspective. Compared to my 8 year old self, I am brilliant. Compared to myself in 10 years; not so much. Therefore, it is safe to say that anything I wrote in the past was written by someone dumber than I am.

DEBB Was Written By Morons

All DEBB is written by humans who are by definition dumber than their current counterparts. Until we develop and implement technology that automatically reads a developer’s mind and updates DEBB in real time, DEBB is written by morons.

I write this with such a strong word intentionally to shock you. DEBB is a great resource to start with. But, unfortunately, far too many people stop there too. That is the mistake. Imagine if DEBB was so accurate that we could write our code without compiling it and just trust that what DEBB says will happen actually does happen. Would you release code that has not been compiled but is only compared with DEBB? I wouldn’t.

Most DEBB Was Not Written By People With Access To The Source

The DEBB that we use is not necessarily written by developers who have had access to the source code for the APIs that we are using. When we read an example or how-to article about writing code there is a very good chance that the person who wrote that has never seen the source code nor has any insider information.

Sit back and let that sink in a bit.

The person who wrote that example or snippet of code probably (hopefully) has more experience with that particular problem that you are reviewing but there is no guarantee. He may very well have never released a piece of software nor even compiled the example!

Consider this as well: I have written hundreds of pages on Core Data and I have never seen the source code. I would love to, but that is unlikely to ever happen. Should you assume that every line of code I write about Core Data is 100% accurate? No; I don’t even do that. I constantly test my assumptions.

Myths Are Born Out Of Lack Of Testing

Every programming language has its own share of myths. Objective-C is no exception to that. I have run across many of them in my career and it is amazing how people will defend them to the very end. Even in the face of absolute proof they will still close their eyes and ears while pretending that it just isn’t so. Ever hear anyone tell you that a method should have only a single return at the end of the method? That one has been around for ages.

There are many myths surrounding our favorite languages and each one of them deserves to be tested and challenged. That testing cannot be conducted by someone else. When you run across one of these myths and it sounds wrong to you test it. Maybe its not a myth, maybe it is real. But the only way you are going to know is by testing it yourself.

If a trusted resource ever tells you that something needs to be done a certain way, look for a reason behind it. If the reason boils down to “because” or “its always been that way” that should be a red flag. If it sounds fishy then test it. Find out for yourself. If you find out its a myth then share that knowledge. Myths grow in the dark. Shed light upon them.

We Are Lazy

Developers are by nature a lazy bunch. We love solving problems but we generally hate doing something twice. Therefore it is easy for us to just accept the word of a trusted source when they say that something just is and let it go at that. However, your users, clients, customers, suffer from that form of laziness.

If we don’t understand why we are doing something it is our responsibility to research it and grok it. If we don’t are we really any better than monkeys?

Read The Docs But Test

The DEBB on any class is a valuable resource. It lets us know what the intention of the class was and the intention of the developer who wrote it. It teaches us one way to use the classes that are available to solve a problem. But don’t take it as the final authority on the subject. That is a quick way to failure and generation of myths.

We should be able to explain every single line of code that we write. We should be able to look at each line and know why its there. If we don’t, remove it and see what happens.

When an error in DEBB is found we should point it out, politely, to those responsible for it. Let them correct it so that the information can be up to date. It is quite possible that the response will be an explanation of why it is the way it is and we can then go back and review it again. The end result is that DEBB will get corrected or we will learn why something has an unusual structure.

Conclusion

I am sure many will object to my tone in this article. Some may find it offensive. It should be. It was intended to shock. But the message is the same.

If you treat DEBB as the final authority then you are elevating it to the same position as the Bible or other holy text.

That is a mistake because I helped write it and I am a moron.