The Rogues talk about documenting code.

 

I may not be a shaker, but by God I'm a mover!

Hey everybody and welcome to episode 79 of the Ruby Rogues Podcast! This week on our podcast we have David Brady.

We also have Avdi Grimm.

Hello from Pennsylvania!

Josh Susser.

Hey from socialist, communist, California! [chuckles]

James Edward Gray.

We are recording this morning after the election. We woke up in a different world and we've decided the Ruby Rogues will marry immediately.

I'm Charles Max Wood from devchat.tv. So it’s the morning after the election. Do they have a pill for that? [laughter]

Nice.

Ibuprofen.

No! We decided at this election, we have to keep the president.

Oh. Anyway, we still have a fit of the laugh just from the preshow. [chuckles] So I’m sorry to everybody for that.

But we are in a great mood this morning. So, moving right along. What do we have?

Yeah so this week we are going to be talking about ‘Documenting Code’. But before we get started, we do have a few things. First off, I want to just mention that we wrapped up the Ruby Nuby Project last week and you can be expecting announcements of the winners next week. We have to get the folks from the Rogues Golf contest and from this contest on to the show, but because of the holidays and just you know, not wanting to really deal with the scheduling issues, we are probably going to be doing those episodes after the beginning of the year.

But thanks to everybody who submitted. They were awesome!

Yeah. Absolutely. We got a ton and they were great.

We have what – how long is it James? It’s like over 2 hours of videos.

Yeah it’s about 2.5 hours of video.

That's awesome.

Yup. And then, we also have Best of Parley. Were you going to do that Josh?

Yes. The best thread I saw in Parley the last week, there was a couple of good ones but the one that I'm picking was titled ‘Crafting outside the Technology World’. And in that, Rod Jenkins was commenting on a discussion we had about craftsmanship outside of the programming world. And I think that came from the conversation we had with Amy Hoy. And then people talked about the things that they do outside of programming that are about craftsmanship for them or craftspersonship. And it’s off to a good start and I have already discovered a couple of good things from there, including finding that one of our Parley members is actually an amazingly good photographer. It’s Chris Hunt and I'm really enjoying the photos on his website. We have a couple of good photographers in the group it turns out. Anyway, it’s nice to have something tangentially related to coding in which is the environment there. So, that's it.

Awesome. So go sign up for parley. You could find the sign up form on rubyrogues.com. All right. Well let’s get this conversation started about Documenting Code.

Documenting code.

Yeah. Do we have a specific set of questions around this? This came from the User Voice forum right?

It did come from the User Voice. Yeah I think they were just asking more in general about practices of documenting code. But I mean, we could probably take it at many different levels you know, from probably down to low level comments, you know up to high-level project documentation and such.

OK yeah. Maybe it’s good to start mapping out the space that way. I do want to start with a disclaimer here about my background. And that's that I spent a couple of years doing technical writing in the 90s or I guess the early 2000s when I needed a break from programming. So I spent two years as a tech writer. And even when I was a developer, I did a lot of work writing specifications and API documentation for code that I have written. So I think I know a lot about this topic which might make me dangerous. [chuckles]

Yeah. So let’s talk about things at that level because I'm kind of curious there, you know. We have the specs and the documentation but, one thing that I have seen as an issue with some of those things is that they don’t always reference the code or the code doesn't always reference the highlevel documentation. And so, it’s sometimes hard to you know, use one as a manual for the other.

Yeah. Can we put that on the back burner for just a moment and before we get into these particular issues, maybe we can like map out the space.

OK.

And discuss how we wanna address it.

Right. So at the lowest level, like James said there's comments and then—

And there's different kinds of comments; we’ve you got like the comment that you actually put inside code to clarify what's going on versus say, something like an rdoc comment, which is like actually a structured comment that's supposed to be turned in to some kind of documentation.

Yeah. So there are I think two audiences for code documentation; there's documentation for people who have to write more of the code, you know, people who are maintaining the code. I call that ‘internal documentation’. And there's ‘external documentation’, which is manual for how to use the code by a client. So, like documentation for an API.

Oh, it’s a good question. There's actually a third audience that I'm running into in our current project and that is the kind of paper work that you give to a potential investor, that you are hoping to give your company and the software to.

That's an interesting thought.

Whoa.

Yeah. And it’s kind of like a do diligence thing. Like, “Oh, so did you write your code? This code is supposed to be PCI and HIPAA compliant so, where’s your meter of documentation?”

That doesn’t sound like code documentation to me. That sounds like something else.

You'd think that. You'd think that.

[laughs] OK. Well I'm willing to entertain that as the third category of code documentation.

So can we pick on the lowly little comment – the one that's buried inside the method. I’d like to comment on that for just a second.

Go right ahead.

My thought is, don’t do it! Don’t do it!

Yeah. My favorite comment on that is ‘a comment is a lie waiting to happen’.

Yeah absolutely. There are some very rare scenarios where I will put a comment in. And one I can think of that I do tend to use fairly regularly is like, if I'm going to rescue an exception but it’s OK for nothing to happen in that particular case. So I’ll have like a rescue but then there would be like a blank line between the rescue and the end, then I will typically throw a comment in there to say, why it’s OK for nothing to happen.

That's fun because I have a shorthand of that. Comment, space and then a winky smiley. So ‘comment ;-)’ and that is a very explicit shorthand. What that smiley is a happy little no op. Happy little no op -- that is the official name of that little block of code. And what it means is you are expecting something to happen here, but nothing happens here. *Winky* *winky* keep moving!

So I usually put the actual word “no op”.

I usually describe why it’s OK for nothing to happen.

That's because you are a better programmer than me.

I'm with James on this one where you are explaining why this particular bit of code is exceptional in some way.

So OK. I wanna hit that real quick because every time I hear a case made for a particular comment, I always wanna think about like, “OK, is there any way I can think of to not put a comment in that case?” Not necessarily always a good idea. I mean, I'm not a 100% against comments, but I always wanna think like, “Would there have been a way to avoid it without making the code less clear?”

90% of the time, the answer is define the method.

Right. Right. And so, in that case, I think if I particularly had do it more than once, I would write a method which took a block, whose sole job was to catch that exception and to nothing with it. And the name of the method would actually explain why ‘ignore exception because blah, blah, blah’.

Oh like ‘no op handler’ or ‘ignore handler’ or something like that. Yeah.

Right and that is the right answer for about 90% of all comments. When you are forcing yourself to clarify what is going on, it means the code itself doesn’t clarify what is going on. So just tuck in a method that says that thing.

Yeah. But just to clarify David, I would not -- I don’t think I would name a method like that ‘no op’ or ‘no op on exception’ or something like that, just because that wouldn’t really add much.

Right. I agree with you. What is a good name there?

Like, ignore time out because we don’t care or something like that. I don’t know.

OK.

[chuckles] That's probably a bad example.

Fail with silent grace. I mean-- [laughs]

Fail with silent grace is the same as creating a method that says ‘no op’.

Yeah.

It’s not. Fail silently is intention relieving – intention ‘relieving’? [laughs] intention revealing.

So there's another approach to this. And that we don’t just have code, we also have tests. And one of my standard moves is when I find myself wanting to put a comment in the code, like literally the first thing I think of after can I do an intention revealing method extraction, is can I write a test case that explains what is going on.

There are pros and cons to this and this is one of the things that drives me crazy about certain types of documentation, is that then you have to go in look in another place. The flip side is that if you are writing comments in your code, you are cluttering your code. So, I don’t know what the perfect answer is but, the fact that I have to go look in a test file doesn't completely appeal to me.

OK Chuck, I'm my finger at you for trying to read code without looking at its tests.

I do sympathize in some way there. I mean in a way, he is right. You know, I also agree that when you are reading code then you should be looking at the test and stuff. But sometimes like if you crack open a piece of code and you just look at some random methods say because stack trace lead you there or something, it’s not always easy to jump straight to the correct test file.

Right.

Right.

And that it’s sometimes difficult to know where that coverage is.

If there were even like some reference in there that I could just click or move to, that would be enough. But then, you are adding comments to the code or adding clutter to the code. And I haven’t really found a way that I like that does this really well.

And there's also a fact that like 80% of the tests that I stumble across in the real world, they are likely including some of my own -- definitely including some of my own -- make for really bad documentation.

Yeah.

And you know, I've seen a lot of tests that just really ignore the documentation aspect of testing completely. I mean, it’s understandable. I mean, we don’t have of time to format things like great literature, but at the same time, there are a lot of little things you can do. Like if you are using RSpec, you can just run with –fs and look at the spec doc that it outputs and see if it reads in a sane way or if it doesn’t make sense. And I see a lot of stuff like if you just read what you had just written, you would often say, “Oh wait a minute, that doesn't read like documentation.” Because I see a lot of like RSpec tests or mini spec tests that say something like, it 2+2=4, that's not--

Right.

It 2+2=4 is not English. And very often, that points to the fact that the test doesn’t have a concrete subject in mind because there is something that it applies to.

OK so, I agree with what you say in the general case however, when I find myself wanting to put a comment in the code and I decide instead to create a test case that documents that, I'm pretty good at writing a test case that documents it.

That's a very good point.

Yes. This is a very small elephant in a tiny room, but be aware also that test case – documentation is designed to take somebody who doesn't understand the code and teach them how it works. And tests make sure that the code works. But tests do something in addition and that is test fair out all of the edge cases. And as documentation goes, if you throw all of the edge cases, right up in front at the user at the beginning of the manual, they will never understand what is going on. And so, Josh you are probably – I'm going to pick on you just because I'm guessing and one of you other guys jump in if I'm wrong – that you probably get the best feel for this. How do you organize around that so that you test suites -- I mean the magic number I am thinking of or the answer that I am thinking of is we should -- step four is refactor your tests. But how do you make sure that your test suite reads like documentation?

I really like the nested context within RSpec for that.

(Yes!)

The ‘shoulds’ and all that stuff in RSpec, I've gotten used to them by now but, they are not really my favorite syntax for assertions. However, the hierarchical nesting of contexts and describe blocks I think is great. And I have a lot of spec files done in RSpec that I use those nested context to describe all of the different edge cases. It’s perfect for that.

OK.

Another thing I’ll say to that is that I've done exercise of deliberately writing a spec with the intention of making it be documentation. And the way I went about that was just I thought up the most basic use case, and then I wrote that the way I would wanna write it in like a README. And then I wrote some assertions after it to make sure that it worked and then I wrote the test, you know, the code that would make it work. And I basically proceeded forward from most basic use case then gradually coming up with edge cases. And I also inserted some comments in to the tests and that was my way of structuring it the same way like aREADME would be structured. And also as a side effect, ordering how I wrote the code that way.

I have to say, I'm much more forgiving with comments in tests as opposed to in the code itself. And the reason is -- and we are going to come back to this intention revealing code -- if you have to put a comment in, 90-95% of the time, it’s an indication that your code isn’t clear enough. And so, I like to coin it as a ‘code smell’, just because it’s an indication of some deficiency in the code. And this case, it’s the communication code as opposed to the functionality.

OK. So can we put a nail in the coffin of literate programming then? [laughter] And if comments are always bad things to be avoided and literate programming is basically comment oriented programming. [chuckles]

Right.

Isn’t illiterate program does nothing but lies? [laughter]

Well I will say that when I did that exercise -- and I’ll put the spec file in question in the show notes -- I was coming at it explicitly guided by the ideas of literate programming. The comments went into the specs not into the end code.

Yeah, I’ll say that I think literate programming is helpful in like teaching code. Maybe like when you are like, “OK. So then we need to do this and that will look like this.” I find that kind of helpful.

Well, I've gone and organized thing for example, if I have a series of steps I need to take then you know, I’ll go in and I’ll pseudo-code in comments, but as soon as I have a line of code or series of lines of codes that translates directly to that line of comment, I delete it. So you can move through things that way. I'm not sure if that's the same thing as literate coding though.

Yeah. I have something that I wanna throw out which is, things that document your code that don’t live in your in the source code files, you know, like don’t live in your project files and--

Can I jump on something that lives in the source code file real fast? Because there is something else that I wanna nail down.

OK. Yeah sure. I can come back to it.

Because we are talking about these comments in the code, the other one that drives me crazy is the rdoc style method definition crap that goes in front.

Yes! Can we talk about this?

It is ugly as sin. And what it is it’s basically what people put there when they don’t know how to name their methods or name their arguments.

I wanna bookmark and back up just a little bit. We are all trying to insert a debug statement at the end of the previous thing. I will accept that literate programs are just a pack of lies, but I also wanna throw out there because we ran into this in our project – our current project – a test file is nothing but a pack of lies until you execute it.

[chuckles] OK.

And we had a test suite that did not get executed for about 3 months. And by the time somebody found it and tried to run it, there had been an architectural flaw in our entire freaking system for 3 months. It took me all weekend to fair it out. I'm very angry about that.

You didn’t do a test first development?

Yeah, basically the engineer who wrote that piece of code failed to execute it. And yeah, there will be some summary executions at our next retrospective.[laughs]

Yeah.

That's why it’s helpful always to put in that bs test right at the beginning and watch it fail, so that you’d know that it’s actually wired into the system. I've made that mistake a couple of times where I'm like happily programing and I'm like, “Wow everything is green! I'm so smart today!” You know. [laughter]

That's why red is good.

Right.

Yeah.

The green dot is a lie!

So, back to rdoc.

Yeah sorry.

No it’s OK. I know that there are about four other areas that we wanna talk about and--

Go ahead go to rdoc. What do you wanna say Avdi?

On the topic of inline comments, I actually put the question out a few weeks ago: “Show me an example of code where the inline comment was necessary.” and I get some interesting replies. Unfortunately, I don’t have a comprehensive list of them in front of me. But the one thing that was repeated over and over was odd handling oddities of other people’s libraries.

That's a great one.

That was the one example over and over. It was either handling some oddity of a Ruby built in library or handling some weird aspect of some gem explaining either why we are calling an oddly or rescue an exception or even explaining why we are monkey patching it -- that kind of thing. Is there a way to get around that?

I think that if you create a sane adapter layer.

Yeah. That would be my first thought too. It’s like whenever I'm going to interface with some other system, I wanna put a layer in there that at least lets me like, mock from my layer instead of theirs and stuff.

But here is the question: “Do you still put that comment into the adapter?”

Yeah it’s a good question. If you have to do some strange thing because it requires it. I would say yes. I actually like that reason for a comment. I think I would support it.

I want to kind to generalize it a little bit, because I do use inline comments in the case where again there is something about the code that I would expect this and I'm seeing this. So I'm expecting one thing and I'm seeing another. And so it clarifies that intention in a way that nothing else really can.

Yeah. Josh said the words ‘intention revealing method’ and that's a pattern from Smalltalk Best Practice Patterns. And I think that is worth pointing out is that you know, intention revealing method and intention revealing variable, are both very viable approaches to avoiding comments, where it’s OK to factor out a method or a variable solely for the purpose of documentation even though it’s not drying anything up.

Oh I would say it’s not just ‘OK’. It’s desirable.

Yeah. You know if you can explain what's going on in a name of a method and its unclear otherwise, think about pulling it out into that method and having a method name say exactly -- even if the method name is kind of chatty, I think that's OK.

Yeah. But I’d recommend staying under 50-character length.

Yeah.

So I have a line of code for you guys and a comment for it. I will classy this as ‘danger’ – deceptive danger. In other words, this code looks deceptively simple, but it is simply deceptive. The line of code was, “new seed = seed * 42942697295 modulo 69069”. Now we extracted that to Rant. This is random number generator. So Rant was def rant and then it had a static -- this was in C, it has static member variable that held the seed -- and it multiplied it by 2^32 -1 and then a modulo by 69069 (which is a prime number by the way). There was a comment, this is a four line method that was the define the line of code and then the close curly brace. Fourth line of code was a comment and it said, “These numbers are magic. DO NOT CHANGE THEM unless you have read Knuth volume two.” [laughter] Because, we had people coming in and changing those numbers; what happens if you changed this number? And the answer is apparently nothing. The game still seems to work, except that you have completely broken the random number generator.

Yeah.

Have we spent enough time on comments?

I just wanna get my funniest comment…

Go for it.

…line in there. I’ve probably brought this up before, but once I ran across a piece of code. It was C C code, so there was ‘#define’ that was defining a constant. The constant’s name was ‘five’, its value was ‘7’ and the comment was ‘11’. [laughter]

That is absolutely the best comment ever. Let me add one more tiny thing about comments. We talked a lot about, you know, do you put in here for oddities or try to explain especially if there are other systems. But even they are be on the lookout for another way to make the code say the same thing. I thought of two examples where I saw a comment recently in a test where it said, it some object and it had a comment there about how some attribute on that object would be nil. And that which required to understand what the test was going to do. I removed that comment and put in a line explicitly setting that attribute to nil. Then you don’t need the comment at all, right? And another scenario that was a Boolean flag being passed method. So it’s just ‘some method (true)’ you know, and there was a comment there explaining what the flag did, which is why those methods are terrible and you shouldn't write one anyway. But in that case, in Ruby sometimes to get around this, if there is just using it as a check in like ‘if condition’ or something, remember that a lot of things are true. So in those cases, I’ll take out the word “true” and replace it with a symbol that explains what the flag is.

Yeah I've been advocating that for a while and I have been doing that in my code for a long time.

Yeah.

And if you have to pass false, I've started using a bang and then the thing that it’s not.

Oh, that's a good idea.

So I’ll do like “!:admin”

Yeah not admin, very nice. So anyways, even when you are tempted, I would just say make the comment your last resort. If you can make the code safe, that's so much better.

Yeah. Can I now finish my crapping rdoc?

No. [laughs] My last comment on comments. Steve McConnell’s “Code Complete”: somebody reading the code who sees a line of code and have comment next to it inline that says something other than the code, will believe the comment -- every time. Honestly, if I have “widget.number=3” and there is a comment that says “four”. Are you really going to believe that I've got an out of sync comment? Or are you going to believe that I'm using zero based math? So Avdi, whatever that program did 11 times, I hope it did it right.

You talk about rdoc, it’s very important.

Yeah. Let me finish my rant. OK. So I hate it. It’s ugly. It clutters the code. But the real thing is you are putting a comment in my feeling is the comment should absolutely add something to the understanding of a code. And those comments are written so that they can be generated into HTML and so they don’t do that job. It’s just crud that clutters up what I'm trying to get through and understand.

OK Chuck, I have a response to that and that's that, I think that many of us, because we do some flavor of Agile development, where we have very high bandwidth communication between team members that we are used to being able to communicate effectively, information about what methods do, if we have a question about something we can just go ask the other person who is working on it or maybe we are even pairing with at the time and can find it out. If you have larger teams or specially separated teams working on APIs or I write an API and you use it but you’re on the other side of the planet in a different division of the company, then you need to have some sort of communication mechanism that takes the place of the high bandwidth, person to person, you know, we talk to each other and stand up every day or paired next to each other all day long. There's just -- you need that communication. And those kind of structured block comments that sit before a method or a class or something like that, those can be incredibly useful for basically taking the place of communication that we prefer to have. So I think there's place for them. It’s not my favorite way of documenting this stuff, but it’s actually really good to have some predictable, understandable way to get that information.

I can kind of agree with that. The problem is that again, we are coming back with this intention revealing code you know, you should be able to look at the method and you know, look at the arguments and understand what it does and what is.

So this goes back to my point earlier about there's two categories of documentation; internal versus external. There is -- are you documenting this code for someone who is going to be opening up the code and working on it? Or are you documenting it as an API for somebody who is going to be consuming it? And if I'm using an API, I really don’t wanna have to open up the code and look inside it to understand how to call a method on it. I wanna be able to look in rdocs or whatever the documentation format is and say, “Oh, I'm calling string reverse. This tells me what that does. I don’t have to go and read the C code for it to understand to how it’s operating.”

I think we are mostly in violent agreement because what you are saying is, “I wanna use this API, I don’t wanna go open up the code and see what it does.” But, the thing is when you are looking at rdoc, you are looking at an external resource *anyway* because it’s generated HTML. So you are not going to go crack open the code, you are going to go look at that. So, all of that stuff shouldn't be generated out of my code, it should be generated out of something else. It could be a README, it could be a wiki, it could be something else but it doesn’t belong in my code.

I strongly disagree, but--

I don’t wanna have this fight right now. I don’t think it’s--

OK.

I think that we’ve both put our positions and we don’t have to agree on everything.

OK.

And—

We just had an election. I don’t think we do agree on everything. [laughter]

I think it’s a good point. I'm glad both of you have brought up your points, because in my opinion you are both right. I agree that there’s a lot of value in there to having that API documentation. I used the API documentation in Rails all the time, going in and finding out what some methods does or which arguments I can pass through or whatever – it’s handy. However, I think it’s worth considering that's mostly handy at the advanced intermediate and up levels [chuckles] Like if I'm a beginner and you give me the API docs, that's not helpful. It’s really not. And I think we do a bad job of catering to that lower level of documentation.

Right. So let’s talk about that. So when I was working at Apple and doing a lot of programming in system 6 and system 7, they had these series of books called “Inside Macintosh”. Did anybody read any of that documentation?

I've heard of them but I haven’t read them.

They did a really brilliant job with these books. It’s always possible to criticize this kind of documentation because nothing is perfect, but the thing that I really liked about it that there are two parts to the documentation for every subject. You had your typical API reference that it went through every data structure and every API call and explain what all the pieces where in detail, and this really important. But the other thing was that every section also had a narrative flow that said, “Here’s how you accomplish your goals.” And they would go through and say, “OK. You wanna do something like opening a window, here's all the steps that you need to do.” And it was basically telling a story and had a lot of references out to the API reference. But, it was basically big blocks of texts with pictures of examples in it and many pages of that. And that was the part that I always read to get all the context to be able to understand all the details of the API documentation.

What you just said right there is the key. The problem with API documentation is there's no context.

Exactly.

It’s that, “This method does this but do the Rails guys intend me to call this when I'm in the controller? Is this thought of like a view thing?” I don’t know that when I looking at that one methods documentation.

That's really interesting because I’m working with team of .NET refugees and their one biggest gripe with Ruby is that they are coming from Microsoft -- and I hate to utter the dark tongue of Mordor on this podcast -- but they could open up the MSDN by hitting F11 or whatever on any function. And it would open up the MSDN reference to it and it would give them the entire method call, the data types of everything. Like if it was an integer, they would then tell you these are the legal values for this integer range because we are really passing in an enum or whatever here. And then, you had three – at least one but sometimes as many as 3 or 5 examples of working chunks of code that use that piece of API to show you why you would use it and how you would use it in context. The thing that makes this really interesting is that the 2 places now that we know did this was Apple and Microsoft. We are not seeing this in a lot of the open source communities. Is that because that there is no market for this product? Or because nobody thinks it’s interesting to go build this? I would love for this to exist in Rails.

So I've seen a fair number of open source project that have good documentation in this regard. If you look at something like device and go to their wiki, there is a ton of examples. There’s a ton of goal oriented documentation.

Mh-hmm.

I don’t think they generated it by any like magical tool that did it and there is no magical way to integrate it with the code, so that you can hit F11 and find that stuff. That's an IDE thing. But the fact that they have created these scenario-oriented documents or pieces of documentation is I think great and makes these libraries much more usable.

Yeah. I also wanted to point out Chuck, when I said I strongly disagree with you, the only point I was only disagreeing with you is that, the farther documentation gets away from the code it is documenting, the less likely it is to be accurate or kept up to date. And so, the whole – Doxygen was one of the things that really started this back in the C days. Actually I think Doxygen may have actually come out of Java and got back ported to C. But anyway, that was a thing to -- you could write comments that could then you could look, there is the comment, there is the code. “Are these in sync?” “Yes they are.” “OK good.” And then somebody else could generate the document.

Yeah. So I kind of agree with that, but at the same time let me pop this doc just a little bit with what David was just saying on how the Microsoft documentation is so discoverable. I think that is a real flaw and actually a major problem with rdoc in general. I actually have a long list of complaints about rdoc now. But, one thing, if anybody was listening to this, absolutely needs to go read the article on ‘Learnable Programming’. I think I've brought it up a couple of times now. But, it’s really about how we discover things and how we see them in context and stuff like that. It’s a long article and it takes a while to read, but it’s absolutely very worth it because it helps you understand how documentation should relate. And basically if you start going through this checklist, rdoc fails it like item one. It’s not -- it doesn't meet the needs. However, what you were saying there about -- and I do agree with -- that as the documentation gets farther away, doesn’t that increase its chance to get out of date. Well OK, first of all, when we split that documentation out from the method, it’s now maintained in two places; the code itself and the method. So at that point it’s a dry violation. And then I've seen plenty of cases where, I'm sitting there reading the code and I'm reading the documentation directly above it thinking, “No. It doesn’t do that.” You know, so it definitely can happen. But also, I think that's maybe a failing of our tools. There's certainly ways they can handle that better. For example, when the tool extracts the external documentation, it can tag it with a show of the current method content. And then in the future, when it’s generating documentation of that show change, it will know that it is out of sync. Or you know, could you do one to say if it’s still valid or something.

As a perfect example as of the utterly wrong solution to obviously the right problem, this documentation even right next to the code can get out of sync. And so one of the Doxygen variant, -- and I can’t remember which language it was in. I wanna say its PHP -- you can actually specify like in variants in the Doxygen block and it would emit unit tests for you. And all of a sudden, you have developers writing their whole tests suite in the comments to the code. And right problem, absolutely wrong solution. Because now you have a test suite that you can’t read mixed in with code that you can’t read. It was an absolute nightmare.

That's awesome.

That's amazing.

I'm confident now that I've defined it that context, I'm confident it was PHP.

[chuckles] I wanna hit on one more aspect of and it’s kind of hard to explain, but it’s another reason to me why -- I really think we have not nailed this domain. And I keep waiting to see even documentation living alongside code, I really feel like we got a long way to go there. And I keep waiting to see the good competitor. But as another way to explain it, there was a big change in a recent version of Ruby where ARGF basically got its own class or something like that, which sounds kind of weird and esoteric until you realize that probably one of the primary motivators of this change was to be able to document what the heck are ARGF is. And in rdocs current form it’s actually almost impossible, right? I mean try the ---while loop you know, you can’t because we can’t queue rdoc keywords. Perl does better in that regard in that it can allow you to document keywords or even arbitrary things; even things like FAQs and stuff. So, I think perldoc is a quite a bit superior in that way. But it’s kind of a symptom of rdoc, right? It that, we can only tie documentation to these certain things: classes, modules, methods, etc. But there are lots of things in a program that aren’t those elements. So how are we documenting those elements if we are going with rdoc? For example, what do you do if it makes perfect sense in this case to have method missing that services 20 different methods. OK so then, how do you document that? Because putting the documentation on method missing is stupid; that is not what calling. And there's elements to the program like Josh said there is context that, yeah you know that this method does this. But actually, its related to this really important configuration file. Where do we document that? The contents of that configuration model or whatever. And to me, that is kind of a reason why this whole system is flawed in my opinion and not a correct approach. That's my personal opinion.

I wonder if Smalltalk could fix this. [laughter]

So—

I'm not kidding. I know it’s funny. I'm not kidding.

It is funny and I know you are not kidding.

So I wanna use that opportunity to segue to a new topic and that is ‘integrated documentation’. So this

Can we get a definition?

Sure. Integrated documentation is documentation that is integrated into the structure of your program. So in Smalltalk, every class had a couple of strings that were associated with it that were the documentation for the class.

Doesn’t Python also have docstrings?

Which got from Lisp, yeah.

Yeah. So this is not unique to Smalltalk, there is plenty of languages that do that. Jose Valim’s Elixir language also integrates documentation. And so, it’s a very interesting thing. In Smalltalk, when you define a method it’s like are you going to put a comment right at the top? There's a lot of the stuff that's just integrated in to the development environment. And there is other environments and languages that do a better job than Smalltalk did too.

And just to be very clear, we are talking about something where you can actually ask the object at runtime about its documentation?

Yes. It’s part of the metadata integrated into the program.

And a good example of this in Ruby is Rake with the desc method, where you describe the task.

Yes. And just having a place where you could put information like that meant that people were more likely to do it.

Sure. Provide more trash cans, people litter less, right?

Yeah. [laughs] Yes. So that part was pretty good. But still, comments are lies waiting to happen. And it was incredibly common that people would not keep their integrated documentation in sync with the code either.

Oooh! Big epiphany! Comments are not lies waiting to happen. Comments are lies waiting to be gotten away with. [laughter] That’s the different between a unit test and a comment. There is no way to check a comment but you can check a unit test.

That's true.

Yup. So what are the pros and cons to that approach Josh?

Oh well, I can think of a few. I think like I said, I think I’ve probably said them already that a pro is you have a place where you can put stuff so it’s sort of an attractor for information. And it’s more likely that people will create that. In Smalltalk, we call that the class comment. Like when you define a class you got a whole window where you can just type in whatever this text you want about the class and how to use it. And that was a pretty common thing that people would do. But the downside like I said is that stuff can get out of sync and there's no way we can really rely on that. I've seen a lot of attempts over the years of people that try and turn those things into stuff that was semantically integrated into the language or the development environment, like our tests and our specs are. But how that be more oriented towards documenting the code or understanding the code rather than being able to assert things about the code are true.

Right.

And some of those are somewhat successful, but mostly it’s basically a hard AI problem. And we don’t have the capability of solving hard AI problems yet.

The problem is that the way we approach our code right now is one dimensional. You start at the top of the file and you move down. And you have instruction, instruction, instruction, instruction while somewhere over here, you got another sequence of instruction, instruction, instruction that is test for your code which is no way to link the two. And if you could – that's what why I originally said I wonder if Smalltalk could solve this because Smalltalk isn’t a one dimensional programming environment anymore. It’s this living ecosystem that you could work from. So I mean, I've seen attempts to do -- it actually makes me sad Josh that you said in Smalltalk, these things get out of sync -- I've seen attempts to do things where somebody will put a show tag, a comment in the code that's some tag and you got Emacs trained to know where that tag is defined and you can jump between those two. It’s like a named anchor point if you will between two places in the project. And what you are trying to form is a horizontal ligature between these vertical, one dimensional lines. Man, am I just downwind from calling---.

No, dude I totally understand what you are saying.

I don’t know if it’s because I'm sitting in San Francisco and--

I actually agree though but like, think about it; that doesn’t just apply to the documentation what David just said. For example when I really started to get good at object orientation, I had to let go of that fact that we are going to start here and go down. You know, now it’s more like, “I'm going to register this observer and they are going to work it out.” [chuckles] I had to let go of the fact that I could go line by line by line and show the execution. You know.

All right. Well, we have been talking about this for about 45 minutes and we've talked a lot about kind of the internal or included documentation. I would love to get into like theREADME and tutorial or external documentation.

Let’s absolutely make a stop at the README. That's important stuff.

Yeah. I think a great place to start with that is Tom Preston-Werner’s “README Driven Development” article.

I have that open in my browser. I was going to link to it. Yup.

Hah! Yes! I finally got you.

[laughs] I honestly love the concept of theREADME driven development where you essentially you write out what you want it to be and then you go build it.

So has anyone else ever done automatedREADME driven development?

What?!

What does that mean?

Automated? Is that like ARDD? That's really close to ADD.

So, I've taken a crack at this. James I know you’ve seen this because you commented on the -when a while back I did a little teeny tiny gem for named keyword arguments, a form of keyword arguments.

Right.

And in order to write that teeny tiny gem, I started out withREADME file, which for simplicity, I think I just made it a Ruby file where the text was in comments. But basically, I wrote a comment and starting out and I wrote the most basic example I can think of using this gem that didn’t exist yet. And then I wrote a little bit of machinery that would run the file through XMP filter -- which if you are not familiar with XMP filter, some of you may have seen me use it in Ruby Tapas -- you can run a piece of Ruby code through that's adorned with some special insert output here comments. And it runs the file and then it inserts the output of each or the value at each point where you put one of those special comments and it inserts the output of the file at the end. And so I wrote a little bit of machinery that would run the README, and it would take what I had entered after those little special adornments. And then, it would compare that with the output where the values that I had put in were replaced with the values that XMP filter had generated. And a success was when they matched. So success was when my example of what the code – what the value of a given variable would be -- was the same as what came out of the other XMP filter. Failure was when there was a diff. and it would then output the diff between theREADME that I had written and theREADME that came out the other end of XMP filter.

That is genius. I have forgotten you did that. And I just went and looked at it again while you are explaining it. Everybody should go look at it. I threw a link in the show notes.

I'm definitely going to go do that because—

I have a project where I'm trying to factor that process out onto its own gem, but I haven’t touched it in a long time.

I am definitely going to go look at that because I did RDD about 6 months ago on a project called “Polyhedra” and if you go to GitHub, ‘dbrady/polyhedra’ you will find aREADME that completely describes an RPG dice class and then a program that implements about a half of it. And the other half of myREADME is a lie that has waited and successfully had its opportunity to be a lie.

I wanna make some comment about what drove me. One thing that kind of drove me to do is it drove me to have an easily readable textual representation – you know, concise textual representation of any kind of value or state that the program might have. So that I can like put in my version, what I thought it was going to be and then it could generate its own version of what that actually looked like.

So I like the idea of what you are doing to keep yourREADME and your code in sync--

I just wanted to say, we've talked a lot aboutREADME driven development obviously, we can see that required reading for this discussion and you should go check it out if you haven’t. But it’s probably just worth stating, theREADME is like a very, very high-level importance. There is a reason that GitHub bugs the crap out of you until you at least provide one, right? And it’s the entry point; if somebody comes to the code, it’s the universal ‘check here first’. So, this is your chance to introduce the project, it's your chance to show basic usage and we mention a few problems, its good time for gotchas. “Oh, do you wanna run my test suite? You won’t be able to do that until you blah, blah, blah.” You know, it’s all that kind of stuff. This is your shot to handle it.

So I think it’s pretty easy to put too little information into your README. Have you ever run into an instance where you felt like there was too much in the README?

Rails. [laughter]

Well played sir. Yes. I think you can overwrite anything.

I think actually in Rails’ defense I believe they just rewrote theREADME in Rails 4 to handle this exact problem.

OK. So we still have more to cover. So can we move on fromREADME now?

Sure. Where should we go next?

I have something I wanna mention as another kind of tool for explaining or documenting code and that's CRC cards.

Oooh.

What?

Just hang with me for a moment. ‘Class Responsibility Collaboration Cards’ otherwise known as Cunningham Cards. So I’ve sat and worked with Ward Cunningham trying to use CRC cards to collaborate things. So I got this straight from the horse’s mouth. There's two ways you can look at using CRC cards; one you can use them as a design tool, where you use them to assist your though process by making things more visible in a way to communicate with the people you are working with. I had a friend who is a post structuralist doctoral student. She called that an ‘object of shared discourse’. [chuckles] And that so they are great for that, but they are also I think even more useful to use to explain a design because they are so dynamic and easy to manipulate in sort of unexpected ways. So Ward, when he sat down and we took a design that we had and we are having trouble working with, and he is like, “Let’s just write, you know, build some cards and document so we can see everything that's going on and see the relationships.” And being able to get everything concretely put on to your card and seeing how things interacted with each other was actually incredibly revealing for understanding the code. And one of the tricks I learned from that was, I would walk around with a stack of CRC cards describing my software when I walk into somebody’s office to have a conversation about it and we would start putting them out on the table and using them to talk about the code.

Sandi kind of talks about that in POODR, right? About how, you know, visualizing the messages between objects really helps you understand the system in general.

Mh-hmm. So I have a distinction question Josh; what you have described to me is what I understand CRC cards to be brilliant at -- which is helping you analyse code. Do you feel that that's the same thing as documenting the code? I mean, would you keep the CRC cards around after the project was done or moth balled or whatever?

After a while you just toss them.

OK.

[chuckles] But there are certain kinds of conversations about code that they are incredibly useful for.

Yes. Yes. Yeah I try to imagine you shipping the code along with like a three-ring binder with like all the little cards like laid out like in a photo album.

I just wanna ask, is there a good way to virtualize those so that other people can see them?

The operative word there is ‘good’.

No, I've seen a lot of attempts to do CRC cards in software and some of them are OK, and some of them are not OK, but I've never seen one that's like super awesome excellent.

If you just want to visualize the relationships, my favorite tool would be OmniGraffle, in that I can put the whole blocks and draw all the arrows. And I love how I can end up moving this guy over later and all the arrows just readjusts without me having to do anything.

Yeah.

Awesome. So one other area I wanna get to – I know we have been talking for almost an hour here but I wanna talk about things like the Rails guides or the wikis on GitHub.

I was actually going to bring up a similar thing into that, you do reach a level where things like books and stuff are almost required. Like Rails is so vast in scope. You know, like something the asset pipeline is huge right? And just to get your head around everything that is going on in the asset pipeline, what you just mentioned Chuck the Rails guide -- it’s one of the best places to do that. They can write focused documentation about specific sub chunks of the system, right? Like chapters in the book.

Right. So, is it I guess the thing that I am getting to know is that, these tend to be like high level explanations, “Here's how you use the library” or whatever. And you know, at the lowest level in the code, I just wonder is it appropriate or necessary or helpful to link out from the code that is related to out to this high level documents or are they completely separated at the levels that they are at?

I like to have them integrated.

Yeah, I like cross linking.

Citations are very useful.

And the reason those documents rock is you read those and that gives you the context. So then you can go to the API documentation and understand what the heck is going on.

Yeah. I wish the Rails guide has more links into the API docs and vice versa.

Yeah.

But the problem is there is no standard API documentation. There is API doc, there is railsapi.com, there is Rails – I mean, there's 17 different API docs.

Well, maybe our next Rogue’s project is to try and sort out how to do better integrated documentation.

That's right. We need to come up with a level two minion project now.

I have to say that thing that I'm enjoying about this episode is that, I mean we agree on some things and disagree on others. But ultimately, we are highlighting as many of the problems with the documentation systems that are out there, as putting up “This is what this do well.” And I love kind of the way this has flowed through that.

And like any software engineering issue, it’s all about trade-offs. And there's cost and benefits.

That's a good point.

Yup.

You know, you wanna be able to communicate about what your code is doing, what its requirements are and what the API is. And there's a cost to accomplishing that, but there is a benefit to it as well.

And I would even add that there are multiple dimensions inside what you wanna communicate and what the trade-offs are. So there are times when a big honk and inside Macintosh product or a big honk in MSDN product is absolutely the right trade off. And there are other times when a single line comment that says, “These numbers are effing magic. Done effing touch them,” is the right trade off. And these are completely different ends of the spectrum for trade-offs. But there's multiple dimensions here and they change over time and based on project and yeah. Just be better programmers. [laughter]

Yeah. Do better. Geez yeah.

I think it’s interesting too though that you know, where we really see them kind of fall apart is like the little comments through the code or whatever to communicate to other coders that are getting in, versus like the high-end API docs or guides or tutorials for people coming in. I mean, you are dealing with people at different levels and when you have a project that is trying to communicate in all those levels, I think that's where we really see it get complicated to the point where we are saying, “Yeah this has this trade-off and this other one doesn’t.”

That's true. It’s like it’s almost like the scope of the conversation. In the project that Chuck and I are working on, I’ve seen nine or ten times and I have written two or three times a comment along the lines of “This is broken. And it needs to be fixed and I don’t have time because I'm also focusing on this other task right here.” And that comment goes into the code, and it stays in the code. And that is not a conversation between me and another programmer. That is a conversation that you need to freak the hell out as team lead or project manager. That's absolute cry for help from the developer to project management, to the team in scheduling. And so yeah, just remember that your comments are at multiple levels of scope.

I wanna hit two more issues real quick. I know we are kind of long time but just real quick; one I wanna say is that don’t underestimate different media. Like video is getting big, right? And we have things like the PeepCodes and stuff which I think we can all agree. RailsCasts are valuable forms of documentation. There's definitely times in which those makes sense. But also, they are being used in more and more areas. And you know, I encourage people to think about that. A lot of times, Aaron Patterson now, when he finds a particularly troubling bug in Rails or he's working on some new feature and he wants to give an early preview of it, he’ll make a short little video -- usually to some awesome rock music in the background or whatever -- and then throw it up on the Internet. And how genius is that? If it’s a bug, then and it turns out he is doing something wrong, then some pedantic person that's watches it will be like, “Oh. Yeah. You do-- Whatever.” But also you know, sneak previews of features that he is implementing. They only exist on his machine or even if they’ve been checked in, they might be hard for you to set up a similar scenario. Whereas in 2-3 minutes he can show you what this thing does and how it works. That's kind of a powerful form of documentation I think.

Yeah. I agree.

And blogs kind of following the same thing – there's the documentation that's not necessarily – I mean, sometimes it is but not necessarily written by the people who wrote the code, but it’s still valuable in the sense that it helps you gain context and get a handle on what it’s supposed to be doing.

Yeah. And then the only thing I wanted to mention; I've been getting pretty in the Hypermedia APIs recently, I read through Steve Klabnik’s Designing Hypermedia APIs’ “book” (which is really good) but in doing that, I realized that one of the powerful things of them is how they kind of forced the documentation issue. In that, you end up building this media type which is how these systems communicate with each other. And you almost have to document that media type, especially if somebody else is going to be writing the other end of it, so that you are explaining these things and stuff and I think that's kind of powerful from a documentation perspective. So, it might be worth noting that some of these techniques we have been talking about lately like SOA and stuff, can maybe help push you to do better documentation.

Yeah. Are there any other things that we need to go over before we wrap up? You said you had two areas you want to talk about. Were those the two?

Those were the two. Yup. I'm done, I promise.

I'm done with my list too.

OK good. I'm not trying to rush to an end; I mean, I really don’t have anywhere have to be right now.

I love the fact that we have too much to cover and too little time.

I do have one tiny little footnote to add. So I'm going to put on my gold chainmail bikini and sticky bun hair so I can pretend to be Avdi and say that, when you are documenting APIs, it’s crucial that you document what exceptions are thrown.

Yes.

Yes. And make sure those exceptions are sane.

[chuckles] Yeah. That they are the right exceptions.

That always helps. Yeah that's always nice too.

Yeah kind of with some kind of module or something so I don’t have to register everything --throws.

Yes. Exactly. So that's my last little footnote.

Well, it’s an important one so glad we got it in there. All right so let’s get to the picks. David, I'm going to start off with you.

OK. So I have been thinking really hard about what kind of deeply involved programming based pick I could pick today. And what I kind of came up with is I talk about having this odd sense of humor. I know a lot of listeners haven’t noticed it yet, but if you listen forward it’s there and Glenn Vanderburg, we were talking with him and I don’t know if he was on the show or if it was in the pre call but I mentioned that I have an inner filter and people are like, “You have filter?” And I'm like, “You should see the stuff that gets caught in it.” And Glenn said, “No. You have an inner goalie,” or somebody else that said “You have an inner goalie.” And it’s not that your inner goalie is very bad, it’s just that you get so many more shots on goal than other people. And that is absolutely true of me. And then I found out last week that I know exactly what my inner goalie looks like. So, if you go to YouTube and just type in S-G-T-K that's stands for ‘Super Great Toilet Keeper’. Yes it’s Japanese. It’s a toilet that plays goalie. It’s a robot toilet that plays goalie. So of course it’s Japanese. [laughter]

Oh dear, I'm not even gonna comment. [laughs]

In fact, I'm just going to submit this without comment. Its freaking hilarious. The only thing I will say is my goalie is not as good as the SGTK. That's my picks.

All right. Hey, you even did it fast.

Yeah. That was 1 minute and 30 seconds.

That's got to be a record. Avdi, what are your picks?

Gosh, I don’t have much this week. I don’t know, I guess I have been watching a show called ‘Prime Suspect’, which I guess is an NBC show. I think Liz Lemon mentioned it on 30 Rock as I was catching up on…

Liz Lemon!

[laughs] …as some not so subtle cross promotion and I went and looked it up on Hulu. It’s a cop show, it’s not bad. Good entertainment. I don’t know, I don’t have programming related. I will say that finally, after many years of kind of wanting one, I finally got my hands on a Wacom drawing tablet and it’s been fun. I don’t do a lot of drawing, but some of the results of having that will be popping up on Ruby Tapas soon and it’s an interesting to have a tool for scribbling I think I feel like I don’t do enough scribbling as a programmer and I should probably do more, you know, putting my ideas down in scribbled form rather than just textual form; pictures and things.

Awesome. Josh, what are your picks?

OK. My first pick is for the Ruby Summer of Code 2013. So have you guys heard about this yet?

Not the new one.

OK. So yeah, Jeff Casmir from Jumpstart Labs is one of the big guys behind this. This came out a couple of years ago. Google does this summer of code every year where they pay college students to work on open source software throughout the year. And they’d always tend to be represented for Ruby projects and I guess they rejected all of them one year. And the Ruby community said, “Screw that! We’ll do our own thing!” and it was pretty good. They are doing this again this year and the amount of code are paying students is actually more than what Google pays their similar code people, but he gave a little talk on one of the parties at RubyConf last week talking about this. So I have a link to the Ruby Summer of Code website that I’ll pop in the show notes. And the timeline is the raising funding from sponsors in December; they are recruiting mentors in January, and students go through the process of signing up or applying and being selected in February and March. By the way, mentors also get paid. It’s a very small amount, it’s not really adequate compensation for the time you spend, but it will be a nice little thank you, I'm sure. So, I guess the companies that wanna sponsor they should get in. So go to that site and there is a place where you can get on the email list and they will get in touch with you.

Yeah, there was some terrific stuff that came out in the last one. So, if you wind up sponsoring or mentoring, just a big thank you from us now.

Yeah. Definitely. There is also a Twitter thing that I'm going to pop in here so you can follow them on Twitter too.

All right good deal.

So that is one. And then, the other thing I wanna pick is—

What's your other pick Dave? [laughter]

What?!

[laughs] Sorry. I could’t help it.

That was ---- on me. [laughter]

Go ahead Josh. Sorry I keep interrupting you. I'm sorry.

[chuckles] Did you have too much coffee today?

I don’t drink coffee. I haven’t had any caffeine today. That's probably my problem.

[chuckles] OK. So I was at Ruby Conf last week. You know, kudos to the team for a great conference but one of the things that was awesome that, there was a man there who was deaf and they had sign language interpreters for him and…

(Yes!)

…a lot of people are commenting on how awesome the interpreters were. And I just got to back that up and say I actually spent a couple of years studying sign language. I'm not super fluent in it, but I can follow along fairly well sometimes, and these were really great interpreters. So my pick for this week is ‘Sign Language’ and if you live in the United States, we have our own flavor of sign languages called ‘American Sign Language’. And to dispel the most common myth or misunderstanding about sign language is that it’s not universal. All the deaf people on the planet do not magically speak the same sign language. Every country has their own sign language. And in fact, ours in America is much more similar to sign language in France than in Britain for historical reasons. But it’s great. I found it was actually incredibly useful for my ability to speak publicly, because sign language engages your whole body in the communication. And I found that I was much more – not only relaxed, but dynamic when I'm speaking on stage and it helped quite a lot. And it’s also very useful to be able to sign with people and more people and more people are being able to sign. And the other thing is that, as I get older, I'm living in terror of losing my hearing because of all the loud concert music that I listened to when I was young [laughs] and my hearing kind of sucks actually, so I decided I would get ahead of the curve and learn sign language before my hearing went away entirely and so help myself learn a form of communication that can help that. So I took some classes of sign language at local challenges. If you live in a sizeable population center, the odds are there are some places where you can learn take sign language classes. I haven’t yet seen that there's anything online that is a good resource for just learning sign language on a website or by videos. Those things can be helpful to supplement your education, but there is no way that you can learn sign language without actually signing with other people. So I was pretending to be David Brady and had a really long pick of that, so that's it for me now.

You can’t pretend to be me without sucking me into it though. There is a television show on right now called ‘Switched at Birth’. And the mother and one of the daughters I think is deaf and Marlee Matlin plays the mom. And there are entire scenes that are completely silent. It’s an honest to goodness completely primetime US TV show that has subtitles on it, because the deaf community is involved or is portrayed in that show. And Liz loves it. I haven’t seen it because of my projects; she loves it and trying to get me to watch it because she keeps laughing at the way they swear or the way they sign things.

I got to chime in here too. Sorry for everybody piling on Josh’s picks. We did it with our kid when we had the baby, we got one to those sign language books that shows you, you know, when you start just trying to teach them like 6 things. They are super relevant to them. You know, change my diaper, milk, things like that. And it was really great. We signed to her from day one and about five months in, she become to sign back to us and see certain signs. And to this day, we actually have like an app on the iPad she speaks great of course. And mostly, she doesn't sign much these things. But, she will sit on the iPad and play with this app that we have where you like click on a word and it shows you the sign for it. And now and then, we are just out and about and suddenly show sign airplane or something that she picked up from this app on the iPad. And when we were in Hawaii, the doorman was teaching her how to do the ‘shaka’, which is how Hawaiians wave to each other. And she picked it up like immediately because she does that kind of stuff all the time. So I've really enjoyed doing it with my kid. One, it allowed us to communicate with her earlier. Two, it’s awesome to be able to give silent instructions across a room full of people and stuff like that. So yeah, great stuff.

And just one last little thing you may notice that as your daughter grows up that there's been a fair amount of research showing that people who grow up signing, the linguistic part of their brain gets integrated with the visual centers of their brain the same was that hearing speaking people integrate their linguistic center with their auditory center. And so people who have grown up signing, deaf people, children with deaf adults, they score remarkably higher on visual acuity and visual processing exercises than the rest of us.

Interesting. I have to say that we did that with my kids -- not to the extent that something like James did -- but yeah, my one year old everything he says, he says a lot as mmma- but he will sign it, the signs are different. And I dated a girl in college that was deaf. And it’s very interesting to see into that world and see how deaf community perceives the hearing community.

Yeah that's like 8 different podcast episodes. There's so much material there.

Yeah. But I'm just saying that it really is a big deal to have something like that. And I also wanna point out that I've had it also pay off; I've dealt with some disabled kids at the church here being a scout leader and things. And in a lot of cases, they don’t communicate well verbally, but they do communicate well through sign. And so, it also helps people who can hear but can’t necessarily communicate.

Yeah. And you know, every now and then you have to work with somebody who is deaf and just being able to communicate with them is great.

Yeah. Makes a great difference. Anyway, James what are your picks?

OK. So I have got a few; the first one is there was some tweeting during Ruby Conf about this talk that I guess Gary Bernhard referred to in his talk in Ruby Conf. I haven’t seen his yet because the videos aren’t out -- I'm sure it’s great -- but I did go watch this other talk called “Integration Tests Are a Scam”. And if you think the title is --- wait, till you get about 30 minutes into it and it gives you the mathematical proof of why integration tests are scam. So if I haven’t hooked you with that, seriously it’s a great talk. It’s probably not as inflammatory as you are thinking. And it’s really mind stretching and good. It’s a little long, so definitely set aside some time for it but it’s worth hanging through the end including actually really good Q&A after he does this big talk. So if you wanna learn some about tests and how they work, that's great stuff. Then my other two picks are a couple of games. The older I get, the less time I have for games of course, so I try to pick the smaller, faster stuff. And a couple of good ones I have gotten off of Steam lately are FTL, which is just a spaceship game where you are fighting against this other spaceships and you work on knocking out individual systems while repairing your ship and stuff as it goes along. It’s got all these random events in it but it’s cheap, its quick. And it’s one of those kind of if you are an old school gamer like me, you will appreciate it. Its 90% of the time, you just die. And so it’s just a question of how long before you die and kind of harsh that way. I enjoy that. So that's FTL. The other one I’ve enjoyed recently is called “Tidalis” I guess. It’s hard to pronounce it. It’s kind of a Bejeweled like match 3 -- I think its Bejeweled I can’t remember -- match 3 blocks are all the same kind of thing. But this one has quite a few twists on it, including these streams which you can direct through the blocks and change around. You don't actually control like the falling blocks, you are doing something else. And there's various blocks that change the way it works. It’s got puzzle modes and then more like actiony Tetrisy kind of modes. And it’s got multiplayer, where you could play competitive or co-op on all these different things. So, pretty rich game there again for like five bucks. So short, sweet. And what I love about both of these is in can fire them up, play for 20 minutes that I have and leave them without being too heart broken. So those are my picks.

Great. All right. So I just have one pick this week. I ran across a problem with my magic mouse and anyway would just quick working with my computer, disconnect randomly. I checked the batteries and all that fun stuff.

It’s magic.

Yeah. There must have been some magic interference. Anyway, I was chatting with a few people and they told me to use the Magic Trackpad. So I replaced it with the Magic Trackpad and I love this thing. It’s so nice. I think part of it is because I did programming almost exclusively on a laptop for a while and so the gestures are pretty natural to me after using a MacBook for that long. But just all the different things that you can do with it and the fact that they have the little videos in the preferences that show you what each one looks like and what it does, is just awesome. So that was just some Apple awesome that I really enjoyed. So anyway, I’ll put a link to that in the show notes and we will wrap this up. Do we have any announcements before we get off the show?

Yes we do. When this comes out, you will have two days left -- counting the day that it comes and the day after that -- to vote for us into the podcast awards. Please go do so.

Yeah. We are all the way at the bottom under ‘technology’. And with that, we will wrap up. We’ll catch you all next week!

Bye!

Goodbye!