Our legacy code often comes along with a large number of interfaces and dependency injection and it's difficult to find where the code actually 'does something'. So the only way I can understand what the code is doing is by stepping through it in a debugger.
If I just try to read it, I end up half a dozen classes away from the method I'm trying to understand in no time.
If methods are factored and named well, the name tells you what it does and you shouldn't have to look at the implementation unless its not doing what it says.
I've found that good OO programs are understood by understanding the classes and messages between them, not by reading the implementations of those methods. Look for the big picture, not the details.
As it looks like you're using .Net, you might want to look into resharper as it implements a 'go to implementation' as well as a 'go to declaration':
http://www.jetbrains.com/resharper/webhelp/Navigation_and_Se...
Comments which describe the code are much less useful than a commentary regarding the code's objectives, in my opinion.
Version 1: http://github.com/akkartik/wart
Version 2 (in progress): https://github.com/akkartik/wart/tree/master/literate
I think that's an unfair characterization. Certainly Github could do more to make code readable, but part of the reason that Github took off and largely replaced other alternatives was that it made it much easier to actually read the code instead of hiding it behind all the extraneous project administrivia. The project's code is still the first thing you encounter on a project's page, even emphasized above its README. Github's code browser is actually pretty excellent compared to a lot of the alternatives. There's fast navigation between files and decent syntax highlighting for a wide variety of languages.
I know that I at least spend a lot of time reading code on Github; probably more time than I spend doing anything else on Github. At any given time, I have a half dozen or so browser tabs open with Github code pages on 3rd party libraries that I'm using.
http://www.storytellersoftware.com
I am actively working on it with students of mine.
Here are some thoughts on reading code:
We read code left to right, top to bottom, but how often is it written that way?
We need to be able to see the order that changes are made in order for us to understand them. Deltas in a version control system store the changes but we lose the order. The time in between commits in a version control system is way too long to understand how code has evolved. Because of this (and the loss of order) there is no good way to animate long term differences in a traditional version control system.
There is not a good place to document the reasons why changes are made. We are supposed to write the reasons why in the commit log but we all know we are terrible at that. How easy is it to remember the 50 changes to 20 files that we made since the last commit let alone describe them in a meaningful way? Very hard. This results in one sentence commit messages that are almost useless.
We could alternatively write reasons why changes are made in code comments. But, this doesn't make a lot of sense most of the time. Who wants to read a comment about how some code has changed if we can't see the old version of it anyway?
So, we make changes, and have good reasons why we make those changes, but we don't write the reasons down anywhere. Storyteller permits a new type of documentation to be created. It animates the changes to code and allows the developer to comment on the changes as they are being animated. Developers can tell stories about why groups of changes are made and distribute them to team members. The stories are searchable from the code.
We are also working on making it have traditional version control functionality to completely replace so-called modern version control (even the most modern vcs seem to be built with 1980's constraints- disk optimized, clunky command line interface, poor visualizations of changes, etc.)
Really cool idea.
