I really enjoy reading other people’s code, it allows you see how others solve common problems, and sometimes even provide parables on what you shouldn't do with yours. It also teaches the much needed skill of reading other people’s code. Unfortunately there isn't a convenient and fun way of reading other people’s code.
Now, ask yourself two questions:
- how many hours a week you spend writing code?
- how many hours do you spend reading code written by someone you don’t know or have access to?
The brave might even ask:
- how much of that code am I confident I understand, and could contribute to?
Many people avoid reading code simply because they hate being outside of their comfort zone. Documentation is an effective use of time if it does what it says. Often times documentation is outdated and unreliable and maybe even lies. Only thing you can be sure of is the source.
Entire businesses have been built on the idea of sharing and writing code, but not reading.
Reading
What about reading? I would argue reading code is as integral to writing as listening is to talking. Everyone likes to talk/write its a form of expression; the art behind the craft, but neither can be appreciated without their counterparts listening/reading.
If I were to hand you a book and ask you to take me to where you would start reading, you would flip past the acknowledgements, table of contents, and other credits and go to the first page, or chapter one. Fantastic.
Now if I were to hand you a stack of code I printed out could you tell me where to start reading it as easily? Could you break the code up into chapters as easily? Should you the reader have to? What if it doesn’t have a main method? :)
Before I answer that, I would like to tell you a story.
When I first started out, I loved writing things from scratch. The clarity of how everything worked together made me feel powerful. I understood everything because I wrote it, I didn’t need to read it, because I wrote it. NIH (not invented here) is basically a thing because rewriting is actually easier than reading the source in developers minds; developers develop and winners win.
Why would anyone rewrite a program so they could add some functionality, when they could just as easily patch the already existing program to do what they want?
This involves the following things:
- Obtaining the source
- Reading & Understanding the source
- Contributing/Patching
- Testing (hopefully)
- Sharing
Most would agree step 2 is probably what they are trying to avoid for the most part which brings us back to our original question.
Where is the first chapter or first page in a piece of software? In my opinion its where the writing begins. This shares many analogies with book writing in general. The architecture of a book may not change (beginning, middle, and end) but they share many parallels to software development having an end goal in mind at the start.
So to answer the question:
Where do you begin reading software? It’s where the writer starting writing it. Thats irregardless of it actually does anything. Does an unfinished story say anything? You can still read it right?
Rainman
That being said, today I am going to start working on Rainman. A tool that will use git repositories (to start out) to allow the replay of git commits and diffs in a sane manner providing transparency of the software writing process.
So you might be thinking that commits are too large to be useful. That might largely be the case, thats why I also intend to provide a recording tool that will allow developers to record their software development process and allow a replay that is more granular and indicative of the development process.
This is still in the inception phase and welcome feedback and ideas in the form of issues here.
