Reading Other People's Code (2012)(mahdiyusuf.com)
mahdiyusuf.com
Reading Other People's Code (2012)
http://www.mahdiyusuf.com/post/32154944661/reading-other-peoples-code?utm=hackernews
23 comments
Yes, with code documentation write "why" not "how."
I like to put it as "what for" not "what."
Maybe this says more about the quality of the code I have to work on or my own lack of ability.
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.
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.
It's not you; it's a case of objectionably-oriented programming:
http://en.wikipedia.org/wiki/Spaghetti_code#Related_terms
http://en.wikipedia.org/wiki/Spaghetti_code#Related_terms
> So the only way I can understand what the code is doing is by stepping through it in a debugger.
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.
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.
Sounds you are being hit with hard end of the OO code stick or Java.
I've been working with Zend Framework 2 (PHP) and it has a ServiceManager class that loads everything, but the configurations can be done in three different ways and it supports aliases and other things that make it really freaking hard to find out where a class came from. It's a huge learning curve. I understand using DI to make code testable but it also seems to make it a lot harder to follow.
Yeah, the 'correct' way of DI, etc. is actually a complete recipe for disaster when it's overdone.
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...
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...
It says "Entire businesses have been built on the idea of sharing and writing code, but not reading." and links to Github, implying that Github is not built on the idea of reading code.
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.
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.
"Only thing you can be sure of is the source." not sure that's even true: http://cm.bell-labs.com/who/ken/trust.html
Unfortunately, it seems that the tool hasn't been worked on.
https://github.com/myusuf3/rainman
https://github.com/myusuf3/rainman
Yeah it's just an empty shell for a project that never took off. Wishware at this point.
I am working on a tool that helps document how code has evolved that I believe is similar in spirit to this post:
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.)
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.)
It would be nice if there was some standard way to structure code so that it could be read through in order and mostly make sense. Maybe even a `how-to-read-this-code.readme' file which laid out an appropriate order to read things in, and making sure that the code is in an appropriate order.
Ah, I've been trying to do just this.
Version 1: http://github.com/akkartik/wart
Version 2 (in progress): https://github.com/akkartik/wart/tree/master/literate
Version 1: http://github.com/akkartik/wart
Version 2 (in progress): https://github.com/akkartik/wart/tree/master/literate
I read this a year ago, I was really hoping for something to come of it.
Really cool idea.
Really cool idea.
I think reading code is a very good practice, and the more you read the easier "step 2" (the understanding bit anyways) becomes. That being said, I don't think reading through huge blocks of comments so that you can understand a function is useful. Forcing yourself to write self-explanatory code with a short docstring is a lot more useful than some hacky code with a huge comment explaining what it does.
I very much agree with this. Succinct comments have the advantage of being easier to keep in sync with code changes.
I start by reading the tests.
To complement this I would suggest anyone to starting looking into BDD based testing frameworks.
Comments which describe the code are much less useful than a commentary regarding the code's objectives, in my opinion.