Wading through Code
I am in the midst of writing a book entitled Clean Code. This book is chock full of lots of code samples; some small, and some large. It seems to me that if you want to teach someone how to code well, you have to get them to look at a lot of code.One of my reviewers complained that he didn't want to have to "wade through a lot of code." This term struck me. I've heard it many times before. I don't know the origin of it; but it's very descriptive. If we are "wading" through code, then the code must be a bog, a swamp, a tidepool, or something shallow and wet that impedes our progress and is uncomfortable at best.
Why do we write such code? Why do we write swamplands and marshes. Don't we want people to glide through our code? Don't we want our code to be effortless to read? What prompts us to write code that other people have to wade through?
Or is that really the whole problem? Could part of the problem be that we prefer writing our own code to reading someone else's? If that's so, then how do we expect to learn? I can tell you from 35 years of experience that you don't learn by NOT reading code. You learn to be a better programmer by reading (wading through) other people's code.
So here's the deal. If you want to learn to be a better programmer, then you'd better get your wading boots on. Because there is a lot of code out there to learn from, and there is not one of us who can claim to be too good to learn from it. You can learn by writing code; but you can't complete your learning without reading a lot of other people's code.
So I am going to finish this book on Clean Code, and I expect that those people who take the trouble to wade through it will benefit from the experience.
!commentForm -r
My favorite definition of an expert is "Someone who knows what all the mistakes look like". Looking at crappy code makes you ask questions you might not otherwise have asked, and makes you consider trends and forces that aren't present (in the same way) in your own code.
He assist in your metaphor, I think that code can be "glided" through if it is code that is:
1. simple, with no rocks or branches in the way.
(It serves one purpose)
2. smooth, so getting accros it doesn't mean stepping in too deep.
(Without multiple layers of conditionals to burrow into)
3. hard, without all those soft and spongy spots.
(no code that needs a ton of comments to make sense)
4. frozen, without constantly getting changed by each blow of the wind.
(water turns to waves, objects get changed in version 1.3 to no longer look like the object in 1.0)
5. well-defined, with a nice edge to it, rather than dips and chunks missing.
(the old C format of start, declare, process, and return rather than a mix and match with no borders)
Then you have clean code of a skating rink that you can skate from one side to the other, rather than a swamp full of mosquitos (bugs) that you have to wade through to get to the other side.
1. simple, with no rocks or branches in the way.
(It serves one purpose)
2. smooth, so getting accros it doesn't mean stepping in too deep.
(Without multiple layers of conditionals to burrow into)
3. hard, without all those soft and spongy spots.
(no code that needs a ton of comments to make sense)
4. frozen, without constantly getting changed by each blow of the wind.
(water turns to waves, objects get changed in version 1.3 to no longer look like the object in 1.0)
5. well-defined, with a nice edge to it, rather than dips and chunks missing.
(the old C format of start, declare, process, and return rather than a mix and match with no borders)
Then you have clean code of a skating rink that you can skate from one side to the other, rather than a swamp full of mosquitos (bugs) that you have to wade through to get to the other side.
Programs must be written for people to read, and only incidentally for machines to execute. ~ H. Abelson and G. Sussman (in "The Structure and Interpretation of Computer Programs)
"Write programs to be read by humans, and only incidentally to be executed by machines."
Can't remember where I read that (I'm sure I paraphrased), but it's a fine adage.
.ed
Can't remember where I read that (I'm sure I paraphrased), but it's a fine adage.
.ed
I believe working(not just reading or re-writing) on bad code really helps improving programming skill. You won't learn anything if you just keep blaming the author. Awaring problems, and trying to solve them does the trick. Good code may teachs you how to do things right; bad code teachs you how to correct things, which is tougher than do things right. I believe both are important for becoming a better programmer.
I know one programmer whose code is always perfect on the first write. (Not me, Lord knows.) I've watched him whip out fair-sized apps on the fly, with never a syntax error, compile error, or logic error. But, he can't debug worth a hoot. Then again, he's never had to debug his own code.
I agree that reading good code helps the reader to see how to do something, but it has to be in a response to how-not to do something. The problem has a natural duality - to understand good code, we have to know what we strive for, and *what we want to avoid*. So reading bad code, reasoning about it and understanding why its bad is equally as important to reading good code to understand and reason why it is good.
Just my thoughts...
Nick.
http://www.fromconcept.co.uk/
Just my thoughts...
Nick.
http://www.fromconcept.co.uk/
Syntax highlighting and "hyperlinking to definitions" helps a lot when trying to grok code. Unfortunately books can't do much but display Courier text in a box. Perhaps electronic formats will be able to provide highlighting and code cross links. I got a pdf of a book which had the code samples highlighted in multple colors.
I write swampy code when I am not quite sure what I'm doing - which is probably most of the time. I've really been trying to keep refactoring in check because it's rather addictive. So swampy is the way the code stays - until the next opportunity to indulge.
My own code looks like someone else wrote it after about a month or so away from it. So I'd guess that most people don't even want to wade through their own code much less anyone else's.
Good code speaks to me. Tells me what it's doing and helps me do what I need to do. It's more like teamwork than wading through marshland. Bad code talks too but it's full of fear, uncertainty and doubt (FUD). You have to watch it carefully and not let it beat you. Really bad code looks like good code but it's full of lies !
Enough silliness. ...
I write swampy code when I am not quite sure what I'm doing - which is probably most of the time. I've really been trying to keep refactoring in check because it's rather addictive. So swampy is the way the code stays - until the next opportunity to indulge.
My own code looks like someone else wrote it after about a month or so away from it. So I'd guess that most people don't even want to wade through their own code much less anyone else's.
Good code speaks to me. Tells me what it's doing and helps me do what I need to do. It's more like teamwork than wading through marshland. Bad code talks too but it's full of fear, uncertainty and doubt (FUD). You have to watch it carefully and not let it beat you. Really bad code looks like good code but it's full of lies !
Enough silliness. ...
It seems to me that "wading through code" feels different in terse languages (Ruby, Haskell) than in verbose ones (Java). I hope your book will address this difference.
Mark said: "I liken programming more to martial arts training than to learning chess."
...unfortunately, the "liken" stopped there without any specific content telling us why he assimilates programming to martial arts training. While I don't believe that playing chess is anything like programming, I don't consider the martial arts to be akin to programming in any particular way, either. While both a certainly very mental, the inner-tube above my belt is some kind of testament to the lack of the physical component in programming that is in martial arts. There is some point to be made about the rigors of training in the martial arts, though. And, if one considers the position of Commanding General, a particular variant of martial artist would be a good "chess player." I guess, though, that in programming, the gi is optional?
Chaz said: "Rob: I don't think he means reading bad code by novices. I think we'd all like to assume his book is going to include a lot of reading good code."
...UB said: "You can learn by writing code; but you can't complete your learning without reading a lot of other people's code."
I wasn't referring to his book and what kind of code might be in it. I know that UB isn't a "wee fellow," but I don't think that he is "a lot" of people, regardless of his many facets! :)
My point is that we need to read good code in order to improve, not "inferior" code. Not only that, but reading fantastic COBOL isn't very likely going to help improve my C++ game. In other words, we need to read good, applicable code in order to distinctly improve, IMO.
Chaz said: "I think you're right that there is something inherently challenging in understanding another person's code."
I think that parts of those challenges are brought forth in this thread. Novice versus adept. Speaking the same language (coding language/patterns language) and interaction with the author(s) all play a part in the "understandability" of a body of code. Let's take a different approach for a second. In a different UB thread Frackin' Variable Naming Contest, ( http://butunclebob.com/ArticleS.UncleBob.FrakinVariable ) I feel that I was able to understand exactly what his code was doing from a not-terribly in-depth look-through of it. I know how to score in bowling and I've previously written a scoring system in code. This "domain area expertise" contributes heavily toward the understandability of code. In other words, I've already gone through a number of the thinking processes related to the challenges of an implementation. The rules of bowling scoring didn't change in the process though, which is not quite as similar to the "real world" as the rule of change in most code development worlds.
In a way, this is a familiarity with a body of code requirements outside of the actual implementation. The more firmly you understand the requirements, the more obvious an implementation is to you. The art of writing great code lay in the presentation of an obvious solution. I find that there are very, very few coders who can easily make a very complex solution seem obvious, especially to those who are not well-initiated into the problem domain.
I also find that there are way too many bodies of code being written by smart people who are basically "non-programmers" and "academically trained, practicality deficient" programmers AND programmers of all types who use "bad" style. Obviously, this last aspect is somewhat subjective, but I think that most can agree that there certainly is such a thing as "bad" style.
To me, Clean Code means accepting responsibility for the code, its content and its presentation. If it doesn't compile and execute properly (in a validate-able way) it is totally worthless. If it is difficult to understand/maintain, then it isn't worth much more.
Take Care.
Rob!
...unfortunately, the "liken" stopped there without any specific content telling us why he assimilates programming to martial arts training. While I don't believe that playing chess is anything like programming, I don't consider the martial arts to be akin to programming in any particular way, either. While both a certainly very mental, the inner-tube above my belt is some kind of testament to the lack of the physical component in programming that is in martial arts. There is some point to be made about the rigors of training in the martial arts, though. And, if one considers the position of Commanding General, a particular variant of martial artist would be a good "chess player." I guess, though, that in programming, the gi is optional?
Chaz said: "Rob: I don't think he means reading bad code by novices. I think we'd all like to assume his book is going to include a lot of reading good code."
...UB said: "You can learn by writing code; but you can't complete your learning without reading a lot of other people's code."
I wasn't referring to his book and what kind of code might be in it. I know that UB isn't a "wee fellow," but I don't think that he is "a lot" of people, regardless of his many facets! :)
My point is that we need to read good code in order to improve, not "inferior" code. Not only that, but reading fantastic COBOL isn't very likely going to help improve my C++ game. In other words, we need to read good, applicable code in order to distinctly improve, IMO.
Chaz said: "I think you're right that there is something inherently challenging in understanding another person's code."
I think that parts of those challenges are brought forth in this thread. Novice versus adept. Speaking the same language (coding language/patterns language) and interaction with the author(s) all play a part in the "understandability" of a body of code. Let's take a different approach for a second. In a different UB thread Frackin' Variable Naming Contest, ( http://butunclebob.com/ArticleS.UncleBob.FrakinVariable ) I feel that I was able to understand exactly what his code was doing from a not-terribly in-depth look-through of it. I know how to score in bowling and I've previously written a scoring system in code. This "domain area expertise" contributes heavily toward the understandability of code. In other words, I've already gone through a number of the thinking processes related to the challenges of an implementation. The rules of bowling scoring didn't change in the process though, which is not quite as similar to the "real world" as the rule of change in most code development worlds.
In a way, this is a familiarity with a body of code requirements outside of the actual implementation. The more firmly you understand the requirements, the more obvious an implementation is to you. The art of writing great code lay in the presentation of an obvious solution. I find that there are very, very few coders who can easily make a very complex solution seem obvious, especially to those who are not well-initiated into the problem domain.
I also find that there are way too many bodies of code being written by smart people who are basically "non-programmers" and "academically trained, practicality deficient" programmers AND programmers of all types who use "bad" style. Obviously, this last aspect is somewhat subjective, but I think that most can agree that there certainly is such a thing as "bad" style.
To me, Clean Code means accepting responsibility for the code, its content and its presentation. If it doesn't compile and execute properly (in a validate-able way) it is totally worthless. If it is difficult to understand/maintain, then it isn't worth much more.
Take Care.
Rob!
Working with someone's code with its original developer, gives really interesting insights both to me and to the developer. Figuring out the lurking objects and constructs within a domain enhances my understanding and wisdom about how different some constructs can be implemented. Finding the appropriate structures and patterns for an already developed code is much more beneficial than making upfront designs and green field developments.
So, rather than reading codes alone, one should prefer to observe codes with its developer and maintainer(?) and make brainstorming over and over again until it starts to be boring. This enables you to become a wise man without aging.
So, rather than reading codes alone, one should prefer to observe codes with its developer and maintainer(?) and make brainstorming over and over again until it starts to be boring. This enables you to become a wise man without aging.
I guess you mean that one way of becoming a better programmer is by reading, or wading, through *great* code? As Spinellis says in his Code Reading: "Fact: If you make a habit of reading good code, you will write better code yourself."
I liken programming more to martial arts training than to learning chess. I've been in the industry for a fair chunk of time, but I still learn stuff from novice programmers. Having to explain information and techniques that have become "obvious" to me to a newbie helps crystalize thoughts in my mind. Plus going through bad code reinforces things you don't want to do again. When you can go through bad code, know why it's bad code, explain to someone else why it's bad, and how to fix it (if possible) then you have progressed a long way on the path of learning this stuff.
We like to think others can glide through our code, but I think you're right that there is something inherently challenging in understanding another person's code. Especially when learning new patterns. Perhaps a worthy goal in writing code is that others *who know the same patterns* should be able to "glide" through it. So in your context, everybody who has something to learn from the book will be wading. And that's OK.
I saw someone the other day asking for examples over on Joel on Software's forum, just examples of "well-crafted open-source code" for just this purpose. Seems a little random to me; I'd rather see what makes it through the filters of publishers and recognized authors or series. But it's the right idea.
Rob: I don't think he means reading bad code by novices. I think we'd all like to assume his book is going to include a lot of reading good code. :)
An aside, though: I have to say that there's yet another level of learning in code that may apply to Rob's chess example as well: Teaching to those less skilled than you. The process of teaching often shows me details I hadn't noticed before. It's kind of a meta-test-driven thing. If you can't explain it, you failed the test because you don't know it well enough. If you can explain your techniques, and your student actually gets it, then you must be as good as you think you are!
I saw someone the other day asking for examples over on Joel on Software's forum, just examples of "well-crafted open-source code" for just this purpose. Seems a little random to me; I'd rather see what makes it through the filters of publishers and recognized authors or series. But it's the right idea.
Rob: I don't think he means reading bad code by novices. I think we'd all like to assume his book is going to include a lot of reading good code. :)
An aside, though: I have to say that there's yet another level of learning in code that may apply to Rob's chess example as well: Teaching to those less skilled than you. The process of teaching often shows me details I hadn't noticed before. It's kind of a meta-test-driven thing. If you can't explain it, you failed the test because you don't know it well enough. If you can explain your techniques, and your student actually gets it, then you must be as good as you think you are!
If nothing else, I think you can use bad code as a learning opportunity by trying to redesign it --> http://codebetter.com/blogs/jeremy.miller/archive/2006/04/09/142543.aspx
I think that you have a point with the "not invented here" (by me) part. However, how does one learn to write better code by reading through a lot of really bad code? What of code written by novices, will gliding through it make one a better programmer?
What I think that you're meaning by saying learning isn't complete without reading a lot of other code is; in order to gain more experience, one must experience many approaches to various coding problems.
I often teach people how to play chess. You can't really learn very much about chess by playing someone considerably less skilled than you. I doubt that you can learn much (that is useful) from a novice's code, either.
Take Care.
Rob!
What I think that you're meaning by saying learning isn't complete without reading a lot of other code is; in order to gain more experience, one must experience many approaches to various coding problems.
I often teach people how to play chess. You can't really learn very much about chess by playing someone considerably less skilled than you. I doubt that you can learn much (that is useful) from a novice's code, either.
Take Care.
Rob!
Add Child Page to WadingThroughCode