Code Reading

I just wanted to say that when I'm in the coding mood/mode, I like to do an insanely large amount of code reading. I go on Github or look at Github Gists, or look at code on-line in tutorials and quickstarts. It's really what helps me the most in learning to code in Python, which I've been doing for a good 6 years now.

There's a whole other side to what I just said that I won't go into too many details about. Suffice to say that I believe in a kind of New Documentation where the purpose of documenting code is precisely for the ambient code-reader who happens to stumble across the code doing searches on the web or on Github.

Think of it this way. If you're writing code that's going to be read by yourself or your team members, you can get away with documenting less or maybe not even at all. But in the open source universe, you have to think of an indeterminate number of people who might read your code 5 or 10 or 50 or 100 years later. So it's important I think to be very "literate" in one's documentation.

You can never take for granted that future code-readers are going to know what you were trying to do, even if they can get your code to work. One thing I learned is that you have to UNDERSTAND the code, how and why it works, along with what it's purpose is. I can write a Python script that does exactly what I needed it to do and yet not fully understand it because I'm just basing my coding on idioms I learned and stuff I saw other coders write in my code-reading experience.

It's tantamount to saying something and not truly understanding it. You can still get the point across to an audience, but what's the point if you don't even fully understand what you are saying? A wise man once told me to only ever speak about what I have knowledge of. I think it should be the same thing with code. Use restraint. Only write code about what you understand and have knowledge of.

I find code-reading a great passtime. I can almost never get the code to run on my machine, but I see how the problem was solved, or at least one possible avenue. Often I find the code very ugly and hard to read, and that's when I go back to the basics and make sure I know what I'm doing when I write code.

I think that a certain responsibility comes from being able to code, just as one has the responsibility to watch what one says when one is speaking. Think before you open your mouth, or before you code something.