"Read The Code" is not a valid answer

time to read 5 min | 827 words

Scott Bellware has a post titled Just Read the Code (or, Let them Eat Cake)

That open source software can be opened and read is a great quality of open source.  But reading code and understanding code are two different things.

Here is a simple example, from my own code With.Cache, it is a small class, but in order to understand what it is doing you have to grok Disposable Actions, Semi Statics and the Local Data concept. And then you need to find out where the properties on this class are used, to understand what it is doing.

There is a reason that my primary tool for exploring through a code base that I am not familiar with is ReSharper for C# and grep for anything else. And that is in a code base that I consider pretty good. Code doesn't stand in isolation, in order to understand what it is doing, you need to understand how it is used, and what is it is supposed to be doing.

I had code bases thrown at me when I wasn't ducking fast enough, and trying to untangle that mess leaves scars. I learned SQL to as a self defence measure.

But then "community" in open source jargon usually refers the the community of people involved in the development of the project rather than the community at large...

Yes, that is true, but it is important to understand the difference in the target audiance. To the Castle team, I can talk using a short handed terminology, because I can assume prior knowledge. This helps make communication efficent, and the code base more understandable if you understand the idioms used. If you don't, you are going to have hard time until you do. In other words, you have to already have an understanding of the code in order to understand the code.

Now, there is a not so fine line between the implementation and the interface of the code. If I am intending to make something that I will use later, that I will be as smart as possible in the implementation, so I can be as stupid as possible when using the interface. This is the way it should be, in my opinion, but it does make the implementation harder to grok, because it is doing more.

To quote Joel Spolsky:

Back to that two page function. Yes, I know, it's just a simple function to display a window, but it has grown little hairs and stuff on it and nobody knows why. Well, I'll tell you why: those are bug fixes. One of them fixes that bug that Nancy had when she tried to install the thing on a computer that didn't have Internet Explorer. Another one fixes that bug that occurs in low memory conditions. Another one fixes that bug that occurred when the file is on a floppy disk and the user yanks out the disk in the middle. That LoadLibrary call is ugly but it makes the code work on old versions of Windows 95.

If you are going into non trivial code base, you should expect to have to invest some time in understanding it. A good code base would help you do it, but again, it requires some knowledge before you can do that.

From Spolsky again:

I think the best way to read somebody else's code is just to SLOW DOWN... it's like deciphering a code, not like reading. Most people have trouble reading code because their eyes are used to reading at a certain speed from reading text written in human languages. But code is much more dense than English, and contains 'secrets' that need to be deciphered by looking elsewhere...

Documentation helps in this regard. Not for the specifics of the code, but to document the what and the how. I am not a fan of documenting the code, but documenting the way you are supposed to use it is important. Once you understand how it is supposed to be used, you can look at the implementation and understand how it enables this usage.