As a profession, we are not known for our communication skills. Logical
computers are so much easier to understand than emotional people. To fully
excel, though, we must be able to do both effectively.

Most outsiders view us as interpreters, translating descriptions into a form
computers can understand. This is not all we do, but developing this skill
will make several other aspects of our job easier.

Why Communication Is Important?

Requirements are usually vague. We actually need to translate ideas into a
form computers understand. A well placed conversation can improve our
understanding of the goal, which in turn may transform a complex solution into a
simple one.

Early in my career, I was asked to convert a list of strings into an html table
with the elements sequenced vertically. HTML tables are much easier to sequence
horizontally than vertically. Those were the requirements, though, and I spent
a good deal of time making them work.

Several days later, I was chatting with the author of those requirements. I
commented on the difficulty, it turns out that he didn’t actually care about
the direction. I could have easily avoided that effort with a five minute
conversation.

Accept Feedback

I’m always right. I know my idea is going to work, I’ve got a vision and all
variant suggestions be damned.

This is extremely dangerous. We need to accept that there might be flaws in
the idea, and listen to the feedback describing those flaws. We don’t want to
spend weeks building something, only to discover it was the wrong thing.

Pretotyping, or doing the bare minimum to prove
the idea will work, is a great technique in addressing this problem. We want to
create the possibility of feedback as early as possible.

Get Along

Enemies accumulate and make life way too hard. It may seem reasonable to piss a
few people off now to get something done, but it will make future interactions
harder. And there will be future interactions, the interest rate on a loan
against our reputation is always too high.

How Can We Get Better?

The Software Craftsmanship
movement says that we should practice outside of work to hone our skills.
Toastmasters is an organization dedicated to just
that. I’ll be joining in August, and I suggest you do too.

Ever wonder how readable people find your code? Do you wish there was a more
objective way to measure this?

Now there is. Introducing
Readable Code, a site targeted
at measuring the time it takes to understand a piece of code.

How It Works

Visit the site

Read the sample presented

When you understand what the sample is doing, click “I Understand This”

The time it took to understand the sample will be recorded, and you will be
taken to a page averaging all of these times.

Call For Help

As you may be able to tell, the site is currently more of a proof of concept
than a valid experiment. Try it out and let me know what you think in the
comments of this post.

Also, I’d like to add some sort of qualitative measure, something to gauge the
level of understanding, rather than just the time, let me know in the
comments. I’ve had a couple of ideas, but most of them add more complexity to
the design than I’m happy with.

Motivation

There are a lot of people in the software development community which are loudly
asserting contradicting advice on what makes code readable. I’m not sure what
the answer is in a lot of these cases, and am tired of these people arguing
without objective data. My hope is that, by providing a place for these ideas
to be measured, we can finally get an objective answer.

I’ve started going through
SICP to try to learn
Clojure in a little more depth. I’m quickly realizing, though, that since some
of the exercises are on the theme of “implement this mathematical equation”,
it’s difficult to do so using TDD.

Exercise 1.8

Newton’s method for cube roots is based on the fact that if y is an
approximation to the cube root of x, then a better approximation is given by the
value

Use this formula to implement a cube-root procedure analogous to the square-root
procedure.

Approach

good-enough?

Because this function provides approximations, not exact values, we first need
to build a function to tell us a value is good enough. This will certainly be
needed in the tests, as our function isn’t going to return exactly 2 when 8 is
given. What’s interesting is we’ll also need it in the main code, to know if
we’re close enough to stop.

Exact values will be easier to build, so we’ll start with the usual base case: 0

Here’s where we build the core of the algorithm, the logic to generate a new
guess. The idea here is to build it up incrementally by making as much of the
expression as possible go to 0.

We’ll start by making $\frac{x}{y^2}$ go to 0. Ideally, we would also like to
make $2y$ go to 0, but that would cause a division by 0 error.

Now we can refactor the duplication out of the two forms:

123

(defn cube-root([n](cube-root1n))([guessn]guess))

The next test requires a little bit of algebraic manipulation. I don’t want to
get the next guess and start recursing in the same step, so I need to figure out
a guess that will require another step, but only one.

Plugging this into a polynomial solver yields -1/2, which will suit our
purposes:

In preparation for a presentation I’m making at Boston Software Craftsmanship in March,
I’ve been practicing a kata to convert arabic numbers to roman numerals. I’ve
based this on a katacast by Corey Haines,
but there are some changes to illustrate baby steps more effectively.