Tim's journal

A brief rant since I don't feel much like talking about the specifics of the progress I haven't been making lately. People I work with, don't take this personally; it's more about a general trend :-)

I'm not very good at reading code, or perhaps it's that I don't like reading code and so I don't do it, and don't get better at it. I'm not sure. In any case, I certainly prefer writing code to reading code. This probably makes me like most programmers. Still, you're supposed to get something out of reading code, and I often don't.

Part of the problem is that code often doesn't have very many comments in it. When I'm writing code, I'm not always the best at commenting it either, but often I find I have to write comments just to keep track of what I'm doing, because otherwise I lose my train of thought. When I read un-commented code, I think "this person must be a better programmer than me, because they can hold so much stuff in their head without writing it down". I get intimidated and my mind shuts down and I think maybe I should be a bus driver.

Maybe people who can keep all that state in their heads are better programmers, I don't know. But when it's just in someone's head, it's not available to someone else who might want to work on the project. A friend wrote recently about the ways in which lack of documentation excludes new contributors from open-source projects, particularly new contributors who have plenty of ability but aren't comfortable joining an often-frat-boyish IRC channel to get documentation. Some people need documentation more than others, depending on their social placement.

I'm already in a project, so I should be able to get information the informal way, but sometimes I feel like I ought to know already. Because I don't like reading code that isn't well-commented, I'll do almost anything else to figure out what's going on -- running it repeatedly with lots of print statements added, for example, which incurs a high cost when builds are slow. Or tweaking test cases fairly randomly and observing the change in behavior, or reading the code the compiler generates, which for whatever reason is cumbersome (just making it visible, not understanding it). That takes a lot of time when in some situations, it would probably just be faster to read the code and develop a mental model in it in my head than to -- as I more often do -- develop a model of what it does using the scientific method, treating it as a black box.

But reading the code often brings up an intolerable amount of performance anxiety for me. I can't understand it because my brain is going "you ought to be able to understand this better". Comments would help because it would remind me that the person who wrote this isn't omnipotent, and had to think hard about it in order to get it right. That they went through a process in order to create it, and the product didn't suddenly spring fully formed from their brain.