Recently by Andrew Wagner
Many people have tried to define software craftsmanship. Corey Haines likes to talk about being positive as part of your profession. Avdi Grimm, in the Confident Code talk he's been giving, talks similarly about how clean code is more enjoyable to work with. Bob Martin points out that nobody likes writing bad code.
So I think that a lot of the Software Craftsmanship is about enjoying writing code. It's about building something that you can be proud of. Generally, it's about being happy to be a developer.
One of the keys to this is to learn a lot of different techniques, and to get good at the techniques that you do know. If you're using the right tools, and using them correctly, it will go a long way towards enjoying what you do. After all, would you rather cut wood by hand with a hacksaw, or with a circular saw?
To that end, Near Infinity is sponsoring and hosting a local Code Retreat on the upcoming Global Day of Code Retreat, December 3rd. The idea behind the event is to work on the same programming problem, repeatedly, all day long. After each cycle of working on the problem, you throw away your code and start all over again. This has a really powerful effect - you no longer get attached to having your code, and finishing the problem. Instead, you focus on how you write the code. Plus, you're pairing with a different person each session, potentially with a different programming language. So you get to see a lot of different approaches - different tools - and how to use them, both well and poorly.
So, if you're interested, check out the details, and sign up!
Consider this seemingly innocuous bit of code, presumably on a User class somewhere:
def manager
manager = User.ceo
User.all_managers.each do |manager|
return manager if self.reports_to?(manager)
end
return manager
end
There are certainly other ways to write this code, but the idea is straightforward enough. This is a pretty small company, and if there are no manager-level employees to whom the user reports, then they report directly to the CEO.
However, as you might have guessed, it's not quite that simple. In fact, in ruby 1.8x, it will always return one of the managers, and never the CEO. The "manager" variable in the block overwrites the variable defined previously. Note, however, that both variables, in some sense, shadow the method name, yet that doesn't come into play at all.
Now in ruby 1.9.2, all is well. The "manager" variable in the block shadows the previous one, but doesn't interact with it. And, to boot, it warns you about what you're doing, if you turn warnings on which of course you should.
However, this unfortunately doesn't help you in the slightest in ruby 1.8. And, in fact, it's worse than that. Here's a more complete implementation of the class, with some tests. These tests pass. Not only that, but they show 100% code coverage! This is why you cannot trust code coverage in and of itself.
So, this is a simple snippet, which behaves in mysteriously different ways between 1.8 and 1.9, gives you no warning in 1.8, and even deceives your code coverage numbers. Here be dragons!
There have been a number of recent blog entries lately about "clean code" and how clean is "too clean"[1]. This is a topic that I feel strongly about, especially since reading Bob Martin's book "Clean Code"[2] a few years ago.
So I've decided to embark on a journey of seeing what it's like to really push myself to keep a very high level of quality of code on a project. Will it be fun, or annoying? Will the code really feel more readable by the end? What would it really be like to be 100% TDD and be able to refactor without fear?
The project is an experimental chess AI. Where most such projects operate on a principle of generating as many positions as possible to look at, this one will "think" more in terms of plans and strategies.
The codebase is in ruby, and here are the tools I've pulled together so far:
- RSpec - I'm using RSpec to specify the behavior of my code. This gives me tremendous flexibility, and it's one of my favorite things about programming in ruby.
- BDD/TDD - The classic RSpec book talks about the process of going back and forth between acceptance tests and unit-level tests. I'm not going all the way to cucumber right now, but I am focusing on writing specs (using rspec) at both levels of abstraction.
- Code coverage - I'm using the simplecov gem to provide code coverage reports. I've hooked it up to rspec so that when I run my tests, it gives me a code coverage percentage right after the passed/pending/failed count, and also generates a more detailed HTML report if I need it.
- Static analysis - Yet another great gem, called Reek. This gem allows me to write a test which simply states that my code "should_not reek". A nice goal to strive for! If my code doesn't pass muster, my tests fail, and I'm forced to fix it before I move on. I've also hooked up flog, flay, and roodi, (this blog entry was a big help in setting them all up). Of these, flog seems to work the best.
The strategy looks something like this:
- Write a high-level specification for a new feature.
- Write a (failing) unit test that moves the codebase in the direction of passing the acceptance test.
- Make the unit test pass.
- Fix any static code analysis issues while keeping the unit tests passing
- If the acceptance test from #1 is still failing, I return to number 2.
One thing I discovered is that it's easy to get excited and write code to pass the feature-level tests while the unit-level tests are passing. To resist this temptation, I've set an additional goal that my unit tests provide 100% code coverage by themselves.
Check out the results if you're interested. So far, there's not a lot to it. The engine "solves" an extremely simple king and pawn "puzzle", where the right move is one of the few legal moves. Still, I think it's a nice framework to build on. And it's fun to be able to see output like this, anytime I want to know the health of my codebase:
Finished in 1.15 seconds
35 examples, 0 failures
Coverage report generated for RSpec to C:/projects/ruby/rueno/coverage
100.0% coverage
flog analysis looks good at a threshold of 12!
flay analysis looks good at a threshold of 12!
[1] Here's a sampling: http://myagileeducation.com/2010/need-we-always-write-clean-code/ , http://xprogramming.com/articles/how-do-we-choose/ , http://xprogramming.com/articles/too-much-of-a-good-thing/ , http://agile.dzone.com/news/three-rs-clean-code
[2] http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 - every software developer should have to read it!
In my spare time, I fancy myself a fan of AI. Mostly, this means sitting around pondering, but with some spare time today, I put together an actual working (though simple) library. I thought I would share a little about it on here. The code can be found here.
Behavior Trees are a way of representing an algorithm as nodes in a tree. The leaf nodes actually perform actions, and nodes higher up in the tree branch depending on the environment. They are often used to model behaviors for agents in first-person games. The idea is that algorithms become very modular and composable when modeled this way.
I'm going to walk through the examples in 'sample.rb' in the code repository. These examples revolve around some very simple behaviors on a list. First, we'll define a couple of actions:
action :pop do |e|
e.pop
end
action :empty do |e|
e.empty?
end
The syntax here is somewhat like rake. I played with a lot of different ideas for this, but this seemed to come out the most readable. We're creating two actions, pop, and empty. An action is a leaf node in a behavior tree, so it actually interacts with the environment. Thus, the actions take a block which takes the environment, e, and does something with it. These are the fundamental building blocks.
Now let's define a sequence node. A sequence node is a non-leaf node, which tries each of its children, and fails if any of the children fail. Very simple. So let's define it:
sequence :pop_twice, [:pop, :pop]
Simple idea, simple syntax! The name of this node is 'pop_twice', and it contains two children, both of which are leaf nodes, and which pop one element off of the list that we're interacting with. Since the first child will succeed (assuming the list is non-empty), the second will always run.
Next, let's do a selector node. A selector node is another type of non-leaf node, which tries each of its children, but returns true if any child node returns true (and then stops looking). You can see, it's sort of the opposite of a sequence in some ways. So, what might it look like? Well, it could look exactly the same as a sequence!
select :pop_once, [:pop, :pop]
This selector has the same children, but notice that the name is pop_once. This is because...drumroll please...it will only pop one item. When the first succeeds, which it will, it is satisfied, and returns true.
Now, lets look at the last two together:
select :make_empty, [:empty, :continue]
sequence :continue, [:pop, :make_empty]
This is the culmination of what this little library can do. Isn't it impressive!? Here, we have two nodes which are defined in terms of each other. make_empty first checks wither the list is empty. If so, then, since it's a selector, it's satisfied, and execution stops. If not, however, it hits the second node, which is continue. Continue pops an item off the stak, and then _recursively_ refers to make_empty. So, what's this going to do? It will keep popping items off the list, until it's empty. Very simple, but a very powerful idea.
And that's about it for now! Hopefully, I will soon add the ability to define custom decorators in the library. Until then, enjoy!
Thanks to Near Infinity's generous training budget, I had the opportunity last week to spend 3 days with several members of the Object Mentors group. These guys have an enormous amount of experience, especially "Uncle" Bob Martin. So I thought I would share a few of the pearls of wisdom they dropped along the way:
- "Programming is a social exercise" - I thought this was a really good point. It was mentioned in the context of pair-programming, but I think it has far-reaching implications. Software development is more than just running through a bunch of formulas and crunching out an answer. Interaction within the team and with domain experts is crucial, to not only build the software right, but build the right software.
- "A refactoring is something that takes a few seconds, or a few minutes at most" - I was really impressed with the importance of automated refactorings in his discussions. I think most of the time that I spend "refactoring" is in small, manual edits, whereas most of the time that he spends is in using automated refactoring to "chunk" his edits. I definitely need to learn these keystrokes and refactorings better. Maybe I should start a "Refactoring Driven Development" movement...
- "Don't put refactoring on the schedule; do it all the time" - Simple, but effective. My tendency is to want to spend all my time refactoring, but this curbs that, because it forces me to refactor while I'm delivering user stories.
- "There are 3 essential design skills: nose, vision, and plan" - A nose for recognizing design smells, a vision for seeing a good design for your codebase, and an ability to come up with a plan to get from point A to point B.
- "Testing trumps good design" - This bothered me at first, but I think it's a really good point. The idea here is not to say that design is not important. But, rather, if you are forced to choose between between a "bad" design that allows better test coverage (e.g., less encapsulation), and "good" design which is hard to test, choose testability. The reason here is that the biggest roadblock to changing your codebase is not bad design, but FEAR of breaking something. If you know you will know when you've broken something, then you can retrofit a better design later.
- "There is self-worth tied up in "finishing" something" - He also drew a distinction between having something working (which some developers will call "finishing" it), and finishing it - making it not only work, but be thoroughly tested, maintainable, etc.
- Presentation layer - he talked about having the thinnest possible UI layer, which talks to a presentation layer to find out everything about how it should render. Then test the UI and business logic completely separately
- "You aren't doing agile development unless you are tracking your velocity and remaining story points in terms of passing, automated acceptance tests" - I balked at this at first, feeling like it was too easy to use this as a performance to beat the team over the head with. After I thought about it, though, it's really about the definition of done. We are done if all the features we said would be working are working. And how can we know this? Only by testing them. Continuously. Which means it should be automated.
- Acceptance tests don't need to be end-to-end, and, in fact, shouldn't be. This is another one that made me hesitate. After all, how do you know the feature is really working unless you go all the way from the UI to the database and back? Well, in short, because you're the developer. There's more value in being able to test features fast, constantly, than in being able to truly test them all the way from one end to the other. Mock/stub out what you need to to make that happen.
- FitNesse is cool. This is the second time I've played around with that tool, and the second time I've been impressed with its power and simplicity. I definitely need to play around with it some more.
Subscribe to Andrew Wagner's posts