Forem: David Wickes

Three Books

David Wickes — Fri, 07 May 2021 15:04:05 +0000

So I was kicking around some ideas with partner-in-crime and work friend Chris James of Learn Go With Tests fame, on the subject of "what even is a 'senior' software developer?". This wasn't an entirely abstract conversation; we were once again trying to work out what the best questions to ask at an interview were - interviews where we were doing the interviewing.

Chris was thinking about what skills and knowledge a "mid level" (again, whatever that is) needs to become a senior developer. I was (once again) bemoaning the number of developers who can spit out a few buzzwords and parrot some fashionable ideas they've seen on Twitter, but then never apply those ideas to their work.

And somehow these two threads turned into the ultimate non-technical interview question:

Which three books have most influenced the way you work?

What, Gatekeeping Much?

We instantly wondered whether we'd be excluding people. And the answer is: yes. It's an interview, the whole point ultimately is to exclude some people - the people who you don't want to get the job. So the better question is: is this question excluding the right people?

And I think it is. This is a question for a senior software developer. I would genuinely expect a senior developer to have read at least three books. Three books that were worth reading, and which were influential on the way they work. This is a knowledege industry (or at least it ought to be and not the fashion industry it feels like half of the time), it's really not too much that we expect the senior developers in our discipline to have read three - more than three - actual books.

Not blog posts - not that I've got anything against blog posts. I've learned a lot through blog posts. But the attribute I'm looking for in a senior is somebody who can think "big" and think "slow", who can pay attention to a long form piece of writing which has ideas in it that won't fit into a five-hundred word explanation. I'd probably accept a journal paper at a pinch. But not a blog post. And definitely not a tweet.

Lol Yes I've Read ...

Of course, this still doesn't weed out the people who try to fake it. Yes, they will say, I've read The Structure and Interpretation of Computer Programs. It was wonderful. Job please.

Well, no - no job yet. Because the next question is:

Please explain how those books have influenced the way you work. Frame your answer as though you were talking to a junior developer.

One of the most important skills of a senior developer is the ability to pass knowledge and skills along to the "next generation". I want a senior developer to make all the developers in an organization better, and especially the
"junior" developers on their team. I don't want them to sit on their mighty tower of 1337 h4xx0r skillz - I need them to be educators and explainers, raising their game by raising everyone else's game. And if they can't explain why these important ideas are important to them, hopefully in a way that will inspire other developers to read the same book, then I really don't understand how they'll fit in with my idea of seniority. Maybe they should go and interview at a place that wants you to invert binary trees on a whiteboard or whatever.

I'll go further: I don't even care that much if it's not a "tech" book. Maybe they learned something from a book about management. Or a book about chess. Or a book about sixteenth century Italian opera fans. It doesn't matter. As long as they can explain what they got from that book in a way that someone with little context in software development can understand, it'll indicate the sort of skills I would be looking for.

So now what do you do?

I'm a Junior / Mid-level Developer...

Ask all of those senior developers you know to name their three books.
... and of course explain why those books to you.
Put them all together in a big unordered list
Think about what you want to be learning next, what's missing from your skill set and then...
Read a book
NOW!

Seriously - read a book. Don't doomscroll Twitter, don't read another blog post about the 27 new technologies you need to learn to be a DevTechOpsDataMonk. Don't learn yet another "Hello World" in the language du jour or the hot new JS framework. Read a book! Now is the time to step up, to move towards mastery of your discipline. Get that book, read that book, take notes about that book, bore your colleagues, friends and family by talking about that book, blog about that book. But read that book and read that book now.

And if not now, when?

I'm a Senior Developer...

Just write down your three books with a quick description and explanation of each, and now you're ready for all those juniors who are beating a path to your door. Let me know your list!

And, of course there's a bonus here - I'll hopefully get to hear about books I ought to read!

Audere Legere

So there it is - does this sound right to you? Are you a senior developer who couldn't answer this question, and thinks it's dumb? Tell me why. Can you think of a better interview question that would test the same areas? Or a better way of asking the same question? Do you think books are just for old people who still think posting reaction GIFs is a thing. Or are you just waiting for me to name my three books? I might do it in a follow-up post. In any case, feel free to hit me up on Twitter or the comments to start a conversation.

Go Luddites

David Wickes — Thu, 11 Feb 2021 16:24:39 +0000

The proposal for generics in Go was accepted today. This, and other things,

There's a trend I've noticed in Go community. It's a mindset that emerges at all levels - from junior developers all the way up to the thoughtleader "personalities" of the community, and... I don't like it.

It's a point of view that implies, and occasionally outright states, that "abstraction is wrong", that "being too clever" is "not idiomatic" in Go. That it's bad to be smart.

I'm going to call them Luddites for now, because it's more arresting, but it really represents the encroaching of anti-intellectualism into our work. Let me give a couple of examples.

The Difference Of Squares

I like Exercism, an online platform for learning a language. Solve problems, review your code, compare it to others. Great fun.

Fun problem: find the difference between the square of the sum of the numbers from 1 to n, and the sum of the squares from 1 to n. Sadly, my first take on this problem in Go has been erased by the sands of multiple Exercism platform upgrades, but originally it looked a little something like this:

package diffsquares

func SquareOfSum(num int) int {
    sum := 0
    for i := 0; i <= num; i++ {
        sum += i
    }
    return sum * sum
}

func SumOfSquares(num int) int {
    sum := 0
    for i := 0; i <= num; i++ {
        sum += i * i
    }
    return sum
}

func Difference(num int) int {
    return SquareOfSum(num) - SumOfSquares(num)
}

Shamelessly borrowed from this solution.

Well, I'm a little mathsy in my spare time, so I thought there might be a way to do this without so much looping involved. Sure enough, these two numbers can be reached by using formulae for square pyramidal numbers and triangular numbers. Leading to something like this:

package diffsquares


func SquareOfSum(n int) int {
    x := (n * (n + 1) / 2)
    return x * x
}

func SumOfSquares(n int) int {
    x := (n * n * n) * 2
    y := (n * n) * 3
    return (x + y + n) / 6
}


func Difference(n int) int {
    return SquareOfSum(n) - SumOfSquares(n)
}

(here's my original)

And in the comments I wrote something to the effect that this was a neat maths hack that simplified the solution.

Then somebody commented. Which is great, and I'm always glad to have people picking apart my shady code. But what they said was not so great. I'm forced to paraphrase as, sadly, that version of the comments system is now long gone. But it went something like this:

This is bad Go code. In Go we favour simplicity and readability, not weird maths hacks. This would be much better written as a pair of for loops.

Eh?????

Go 2.0 Generics

So today the proposal for generics in Go got one step further towards appearing in the language - it was accepted! Sure, some people have some problems with the specifics, but I want to focus on a vocal minority (well, I hope they're a minority) who oppose generics.

There's been some reaction:

// Detect dark theme var iframe = document.getElementById('tweet-1357077809869504512-828'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1357077809869504512&theme=dark" }

And the one that sparked this rant...

(sadly I can't link you to this tweet because, after I told the author it was stupid, they deleted it. And then blocked me. Shrug.)

followed by:

They went on a bit, but they deleted it for a reason so let's not pile on. But it's not the first time I've seen or heard this sort of opinion:

Go is meant to be simple! Generics aren't simple.

Go doesn't need generics, I'm happy writing Go without generics. Why do I need generics now?

Go is meant to be readable! I can't read generics, but I can understand a nice for loop.

I can't understand code written with generics, so I like Go.

Seems familiar? That's why I'm writing this?

Do You Believe In Magic?

The maths I wrote for the Exercism exercise isn't complicated. In fact, I'm pretty sure you can read it out loud and understand it. What you might not understand is why it works. Fine. Maybe it seems like "magic" to you - no, you don't believe in magic. But you do know that "magic" in your code is A BAD THING, or at least that's what someone told you once.

But, to quote Arthur C. Clarke

Any sufficiently advanced technology is indistinguishable from magic.

It's not actually magic, it's not even mathemagic. It's just mathematics. You can go to those Wikipedia pages and read them and - boom! - you now know why it works. It happens to be faster that looping, but more importantly it's correct - it's simplified the looping down to single formula.

Yes, that's right, I'm claiming that it's simpler. Loops are not simple. Loops are, to be frank, a quite hard. To read them you have to move your eyes around a bit, walk the code, jump back to the top again, repeat... Sure, you may be more familiar with loops, but that's because you see them every day in Go.

You wouldn't write a loop to add two numbers together? Or to multiply them? This is no different. Things don't become complicated because you're being clever; things become complicated because you're being dumb.

So Why The Generics Hate?

There's a lot of talk about generics adding complication. No, they add another tool. You don't like it, you don't use it. The problem with this particular tool is that developers are remembering the garbage code they've seen written using generics in all the wrong ways. Prematurely abstracted supertypes that have no basis in reality, increase complexity, introduce incidental coupling where there should be none or decouple things that should be coupled. They remember this code because they wrote it all ten years ago in Java and now they're worried it's going to be all over Go.

Well, it probably will. But I reckon there's just as much garbage Go being written right now by folks who don't know basic arithmetic, how HTTP works, or when you should or shouldn't be using interface{}. They will move on to writing garbage prematurely abstracted Go with generics, never write a test first, change job every year, and get called rockstars or 10x developers. I'd try and avoid them and their codebases.

Or perhaps you're new to programming per se, or Go is the first typed language you've used. You're probably used to the playground fights about "lol no generics" and have grown up defining your language, and yourself, as "anti-generic". A sort of weird parochial view of programming - "we don't need your fancy city generics here in Goville".

Both these views are understandable, but nevertheless pretty dumb.

Consider the parable of the Blub programmer by Paul Graham. Don't consider all of it as parts are dumb and out of date, but ask yourself, do I think that generics are useless and unnecessary because I just don't understand them? All those other languages and programmers using generics - are they just being fancy for no reason? Are they just showing off and making code that nobody can read or test? Apply this thinking to all the features and techniques you can think of - do you think I have a deployment pipeline that runs automated tests at work because I'm showing off? Because I'm brainwashed by the Accelerate people and I should really just be FTPing the code to a server somewhere?

Programming is Abstraction

To finally claim that abstraction is dangerous and wrong... please. Heaven help me please - abstraction is the very soul of programming. If we weren't writing our own abstractions when we write code we'd be sitting there staring at a 10000 line main function wondering what on earth this thing did.

Abstraction is our only tool in fighting complexity. Well, the only one that works as the documentation is out of date. We use it with our training and our intelligence and hope to hell we make something beautiful at the end.

Beauty is more important in computing than anywhere else in technology because software is so complicated. Beauty is the ultimate defense against complexity.

-- Edsger W. Dijkstra

Anything - ANYTHING - that gives us another way to abstract in our software is undeniably a VERY GOOD THING.

And generics are just another tool for abstraction. You might not understand it when you first see it - or second, or third. You might not understand how or when to use it. But that doesn't make it more complicated. It's not less readable. It's just making a demand that you learn something new and - as always - have the good taste and intelligence to use it well.

Read a Damn Book

Here's some takeaways for you to angrily repost on Twitter:

If you don't understand it, then you should try and learn it. You work in a knowledge based industry.

If you don't understand it and don't want to learn, then I'd seriously consider my career options: you work in a knowledge based industry.

If you do understand it, but somehow think that it's bad because other people won't understand it or will use it badly - well, I'm sorry, but that's all of programming. Stupid is as stupid does, and if you're going to use these new tools to make your code unreadable, that's on you - not the tools.

Of course, you don't think that. You think that these features are great but should be reserved for "senior" programmers who "know how to use them". You want a language that your underlings can't make mistakes in? This carries the idea that is still prevalent in a lot of places that Go is a "training wheels" language, designed to prevent you from making mistakes. Which is crap. It's minimal and opinionated, it's not idiot proof.

Conclusion

Programming is best when you use all the tool of abstraction at your disposal - functions, arithmetic, naming, modules and yes generics - to reduce complexity. Making things simple is hard - you need to learn, write and think hard.

Complaining about "clever" language features is like moaning about anonymous functions or irrational numbers. Stop being dumb, and stop promoting dumbness.

P.S. You should also probably do TDD.

Fizz-buzz in TypeScript

David Wickes — Thu, 22 Oct 2020 11:42:40 +0000

Often as software developers we are asked to demonstrate basic competence with a programming language in order to secure employment. TypeScript's current popularity means it's very important that we are comfortable writing simple exercises in it. This post will show you how to write 'fizz-buzz' in pure TypeScript, without relying on any other languages or libraries.

What is 'fizz-buzz'

'Fizz-buzz' is a simple game you can play in company. Players take turns counting from one upwards, but must apply the following rules:

If a number is divisible by three, say "Fizz!" instead
If a number is divisible by five, say "Buzz!" instead
If a number is divisible by three and by five, say "Fizz-Buzz!"
Otherwise, just say the number as you would normally

This is often translated into an exercise where, when you provide your program with a number, it responds with correct thing to say were it playing a game of 'fizz buzz'.

Step One: Numbers

First of all we will need some numbers. Unfortunately, TypeScript does not come with any predefined number system so we will have to write our own, including some literals. Happily we only need the natural numbers, which are easily defined:

type N = Z | S<unknown>
type Z = 0
type S<N> = [S]

Using this we can quickly define enough numeric literals for our purposes:

type N1 = S<Z>
type N2 = S<N1>
// ...
type N14 = S<N13>
type N15 = S<N14>

We will need only one operation on these numbers, a way of subtracting one from a number:

type Sub1<N> = N extends S<infer P> ? P : Z

The other arithmetic operations (which we don't need for this example) are left as an exercise for the reader.

To test whether this is all working, we need to run our program through the TypeScript interpreter. The fastest way to do this is to write the following expression into VSCode:¹

type TEST = Sub1<N3>

and hovering the cursor over TEST. You should see the interpreted expression displayed.

Step Two: Truth

In order to test for properties of our numbers using checks like 'equal' or 'less than' we will need some algebra to express truth in. Happily we can use the built in values in this case:

type BOOL = true | false

This gives us enough to define Equal and LessThan recursively for our numbers²

type Equal<Na, Nb> = {
    0: Nb extends Z ? true : false
    1: {
        0: false,
        1: Na extends S<infer Pa> ? Nb extends S<infer Pb>
            ? Equal<Pa, Pb>
            : never
            : never
    }[Nb extends Z ? 0 : 1]
}[Na extends Z ? 0 : 1]

type LessThan<Na, Nb> = {
    0: false,
    1: Na extends Z ? true
        : Na extends S<infer Pa> ? Nb extends S<infer Pb>
        ? LessThan<Pa, Pb>
        : never
        : never
}[Nb extends Z ? 0 : 1]

Again, we can manually test this:

type TEST = Equal<N1, N1>

Step three: predicates

The two important predicates we need to implement fizz-buzz are IsMultipleOfThree:

type IsMultipleOfThree<T> = {
    1: true
    0: {
        0: false,
        1: IsMultipleOfFive<Sub1<Sub1<Sub1<T>>>>
    }[LessThan<T, N5> extends true ? 0 : 1]
}[Equal<T, N5> extends true ? 1 : 0]

and the very similar IsMultipleOfFive:

type IsMultipleOfFive<T> = {
    1: true
    0: {
        0: false,
        1: IsMultipleOfFive<Sub1<Sub1<Sub1<Sub1<Sub1<T>>>>>>
    }[LessThan<T, N5> extends true ? 0 : 1]
}[Equal<T, N5> extends true ? 1 : 0]

You may demonstrate that the above works by writing a test in a similar way to those above.

Refactor

A pattern is occurring repeatedly in our code, which we can extract out into its own operation:

type Ternary<B, P, Q> = {
    1: P,
    0: Q
}[B extends true ? 1 : 0]

We can now use it to increase the readability of some of our previous definitions:³

type IsMultipleOfThree<T> = {
    1: true
    0: Ternary<LessThan<T, N3>,
                 false,
                 T extends S<S<S<infer P>>>
                    ? IsMultipleOfThree<P>
                    : never>
}[Equal<T, N3> extends true ? 1 : 0]

Step four: fizz-buzz

Now finally we can write our fizz-buzz program. We will need to define the possible outputs:

type FIZZ = 'fizz'
type BUZZ = 'buzz'
type FIZZBUZZ = 'fizzbuzz'

This, along with our previously defined Ternary function, allows us to write the fizz-buzz program very succinctly and expressively:

type FB<N> = Ternary<IsMultipleOfThree<N>,
    Ternary<IsMultipleOfFive<N>, FIZZBUZZ, FIZZ>,
    Ternary<IsMultipleOfFive<N>, BUZZ, N>>

and can be tested (and used) as we have seen above:

type TEST = FB<N15>

Step five: going further

This simple program could be improved by adding some error messages and error handling. For instance, at present if we subtract one from zero we get zero, when really we should be seeing some sort of error. We should also think about ways in which we can handle these errors.

In addition, many fizz-buzz exercises require the operation to be applied to more than one number at once, held in some sort of list structure. Such a structure is, again, not present in TypeScript but can be quite quickly defined using methods similar to the above.

Final thoughts

Less experienced developers may be tempted to solve fizz-buzz by using JavaScript, the language which TypeScript parsitizes and also embeds within its syntax. For instance:

const fb = (n: number): number | string => (n % 3 === 0)
    ? ((n % 5 === 0) ? 'fizzbuzz' : 'fizz')
    : ((n % 5 === 0) ? 'buzz' : n)

but obviously this code is just written in JavaScript, using TypeScript built in values as some sort of rudimentary type checker, and not in TypeScript, which is, as we all know, a dynamically typed and interpreted programming language.

This post is heavily inspired by this post by Kyle Kingsbury, which showed me the light.

Edit: changed the implementation because I could...

VSCode is by far the best TypeScript interpreter available, as it correctly evaluates our expressions. IntelliJ, in contrast, is buggy and cannot evaluate expressions that are even slightly recursive or nested. The ergonomics of these interpreters are all peculiar, it would be good if someone could write a simple TypeScript interpreter that wasn't embedded in an editor. ↩
Some of the peculiarities of the TypeScript syntax mean that we need to introduce a little indirection in order to write recursively. This is again unfortunate. ↩
Again, the peculiarities of TypeScript mean that we cannot entirely do away with the {0:... 1:}[ ... ? 0 : 1] syntax, as it gets huffy when the defined symbol is referenced directly in the same expression outside of a 'block', but it's still an improvement. ↩

How To Spell JavaScript

David Wickes — Fri, 08 May 2020 10:28:39 +0000

I thought I'd explain how to spell JavaScript, and go through some common mistakes developers encounter when writing the word.

Javascript

Nope, you need to capitalize the 's'. It's camel case, like all the worst programming languages.

JavaSCRIPT

Too many capital letters now.

java_script

Go back to writing Python or Ruby or whatever.

JAVASCRIPT

NO IT'S NOT COBOL
OR BASIC
GOTO 10

java-script

Although Brendan Eich wanted to write "Scheme for the browser", he didn't and it isn't. So no kebab case for you.

ECMAScript

Oooooh check you out, smarty pants. Technically this is correct, but in reality it sounds like a skin condition. So no.

TypeScript

Well done, you've got the camel case right. But you've forgotten how to spell "Java" and it looks like you've written any randomly all over your code.

ClojureScript

Not only can't you spell "Java", now you can't spell "Closure" and you're putting the parentheses in the wrong places.

CoffeeScript

Only valid in 418 responses.

ActionScript

How old are you?

NodeJS

NodeJS isn't the name of a language; it's the name of a browser project that got badly out of control.

Java

I mean, given that you're probably writing your JavaScript like it's Java this is at least honest.

JSX

The 'X' stands for "wtf is all this HTML doing in my JavaScript?"

ESNext

You're writing a language from the future. Stop it. What are those ridiculous looking operators doing anyway? You really need them? You really missed waiting for your code to compile so much that now you're compiling your JavaScript into JavaScript using JavaScript?

LiveScript

Brendan? Is that you?

Résumé / CV Sift

David Wickes — Wed, 18 Sep 2019 06:41:35 +0000

So we're hiring -- who isn't? -- and my colleague hands me a stack of CVs. That's 'Curriculum Vitae' here in Merrie Olde England, aka a "résumé" for those of us who enjoy using accents.

"These are the ones I'd like to interview," they say, "but there's still too many. Could you take look at them?"

"Well this one for a start," I say, handing them back the first CV on the stack. "There's two typos in the first paragraph."

"What? Why does that matter?"

It matters. It matters a lot. When I'm going through a stack of résumés I'm not looking for reasons to accept, I'm looking for reasons to reject. And quick ones too; we can get hundreds of applications for a position, especially for a junior role, and I have an actual job to do at the same time. So I want to get rid of 90% of these applications. And the ones with typos are the first to go.

If you can't be bothered to proofread your own CV a few times, or get a friend to read it over, then I'm not going to read it. Why would I hire someone who won't take the time to check how to spell "JavaScript"?

If your CV is more then two pages (one in the US), then I bin it. I do not have time to read your life story. No, changing the font size to 7pt won't help you. You will have to cut stuff.

I select on other things too -- poor formatting for instance -- but you get the idea.

Some people think this is unfair. I get told that we're hiring developers, not writers, and who cares if they can't spell.

The first thing I'd say is that this is fairer than just binning 50% of the applications from the start, at random. Yes, I have seen that done.

But also, these criteria; what are they really testing for? Concision and accuracy. These are two excellent attributes for a developer to have, as well as the diligence to check your work before you send it off.

I want to hire someone who cares, who has a sense of pride in what they produce. And I think that starts with the CV and the job application.

What do you think?

TDD an Analogue Clockface in Go

David Wickes — Tue, 16 Jul 2019 21:42:05 +0000

I wrote another chapter for @quii's very splendid and worthwhile book Learn Go With Tests - this one's all about drawing analogue clock faces using SVGs and the math package.

The chapter introduces the math package (we do some trigonometry!) and touches upon some of the issues of using floating point arithmetic. We also look at how to test an SVG... with some (perhaps) surprising consequences.

It's a fairly late chapter, so I'm expecting most readers to have a good bit of test driven development under their belt, and to also know a bit about Go. But you don't need to know (much) mathematics or anything about SVGs and XML - I've tried to pitch it so that it will be accessible to everyone. Please tell me if it's not!

If you enjoy this, or even if you don't, the rest of the book is even better and completely free.

And if you're playing along at home, you can take a look at all of the source files for the iterations of our clock face generator code here.

Anyway, on with the show...

The Problem

You want to make an SVG of a clock. Not a digital clock - no, that would be easy - an analogue clock, with hands. You're not looking for anything fancy, just a nice function that takes a Time from the time package and spits out an SVG of a clock with all the hands - hour, minute and second - pointing in the right direction. How hard can that be?

First we're going to need an SVG of a clock for us to play with. SVGs are a fantastic image format to manipulate programmatically because they're written as a series of shapes, described in XML. So this clock:

is described like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg"
     width="100%"
     height="100%"
     viewBox="0 0 300 300"
     version="2.0">

  <!-- bezel -->
  <circle cx="150" cy="150" r="100" style="fill:#fff;stroke:#000;stroke-width:5px;"/>

  <!-- hour hand -->
  <line x1="150" y1="150" x2="114.150000" y2="132.260000"
        style="fill:none;stroke:#000;stroke-width:7px;"/>

  <!-- minute hand -->
  <line x1="150" y1="150" x2="101.290000" y2="99.730000"
        style="fill:none;stroke:#000;stroke-width:7px;"/>

  <!-- second hand -->
  <line x1="150" y1="150" x2="77.190000" y2="202.900000"
        style="fill:none;stroke:#f00;stroke-width:3px;"/>
</svg>

It's a circle with three lines, each of the lines starting in the middle of the circle (x=150, y=150), and ending some distance away.

So what we're going to do is reconstruct the above somehow, but change the lines so they point in the appropriate directions for a given time.

An Acceptance Test

Before we get too stuck in, lets think about an acceptance test. We've got an example clock, so let's think about what the important parameters are going to be.

<line x1="150" y1="150" x2="114.150000" y2="132.260000"
        style="fill:none;stroke:#000;stroke-width:7px;"/>

The centre of the clock (the attributes x1 and y1 for this line) is the same for each hand of the clock. The numbers that need to change for each hand of the clock - the parameters to whatever builds the SVG - are the x2 and y2 attributes. We'll need an X and a Y for each of the hands of the clock.

I could think about more parameters - the radius of the clockface circle, the size of the SVG, the colours of the hands, their shape, etc... but it's better to start off by solving a simple, concrete problem with a simple, concrete solution, and then to start adding parameters to make it generalised.

So we'll say that

every clock has a centre of (150, 150)
the hour hand is 50 long
the minute hand is 80 long
the second hand is 90 long.

A thing to note about SVGs: the origin - point (0,0) - is at the top left hand corner, not the bottom left as we might expect. It'll be important to remember this when we're working out where what numbers to plug in to our lines.

Finally, I'm not deciding how to construct the SVG - we could use a template from the text/template package, or we could just send bytes into a bytes.Buffer or a writer. But we know we'll need those numbers, so let's focus on testing something that creates them.

Write the test first

So my first test looks like this:

package clockface_test

import (
    "testing"
    "time"

    "github.com/gypsydave5/learn-go-with-tests/math/v1/clockface"
)

func TestSecondHandAtMidnight(t *testing.T) {
    tm := time.Date(1337, time.January, 1, 0, 0, 0, 0, time.UTC)

    want := clockface.Point{X: 150, Y: 150 - 90}
    got := clockface.SecondHand(tm)

    if got != want {
        t.Errorf("Got %v, wanted %v", got, want)
    }
}

Remember how SVGs plot their coordinates from the top left hand corner? To place the second hand at midnight we expect that it hasn't moved from the centre of the clockface on the X axis - still 150 - and the Y axis is the length of the hand 'up' from the centre; 150 minus 90.

Try to run the test

This drives out the expected failures around the missing functions and types:

--- FAIL: TestSecondHandAtMidnight (0.00s)
# github.com/gypsydave5/learn-go-with-tests/math/v1/clockface_test [github.com/gypsydave5/learn-go-with-tests/math/v1/clockface.test]
./clockface_test.go:13:10: undefined: clockface.Point
./clockface_test.go:14:9: undefined: clockface.SecondHand
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v1/clockface [build failed]

So a Point where the tip of the second hand should go, and a function to get it.

Write the minimal amount of code for the test to run and check the failing test output

Let's implement those types to get the code to compile

package clockface

import "time"

// A Point represents a two dimensional Cartesian coordinate
type Point struct {
    X float64
    Y float64
}

// SecondHand is the unit vector of the second hand of an analogue clock at time `t`
// represented as a Point.
func SecondHand(t time.Time) Point {
    return Point{}
}

and now we get

--- FAIL: TestSecondHandAtMidnight (0.00s)
    clockface_test.go:17: Got {0 0}, wanted {150 60}
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v1/clockface 0.006s

Write enough code to make it pass

When we get the expected failure, we can fill in the return value of HandsAt:

// SecondHand is the unit vector of the second hand of an analogue clock at time `t`
// represented as a Point.
func SecondHand(t time.Time) Point {
    return Point{150, 60}
}

Behold, a passing test.

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v1/clockface 0.006s

Refactor

No need to refactor yet - there's barely enough code!

Repeat for new requirements

We probably need to do some work here that doesn't just involve returning
a clock that shows midnight for every time...

Write the test first

func TestSecondHandAt30Seconds(t *testing.T) {
    tm := time.Date(1337, time.January, 1, 0, 0, 30, 0, time.UTC)

    want := clockface.Point{X: 150, Y: 150 + 90}
    got := clockface.SecondHand(tm)

    if got != want {
        t.Errorf("Got %v, wanted %v", got, want)
    }
}

Same idea, but now the second hand is pointing downwards so we add the
length to the Y axis.

This will compile... but how do we make it pass?

Thinking time

How are we going to solve this problem?

Every minute the second hand goes through the same 60 states, pointing in 60 different directions. When it's 0 seconds it points to the top of the clockface, when it's 30 seconds it points to the bottom of the clockface. Easy enough.

So if I wanted to think about in what direction the second hand was pointing at, say, 37 seconds, I'd want the angle between 12 o'clock and 37/60ths around the circle. In degrees this is (360 / 60 ) * 37 = 222, but it's easier just to remember that it's 37/60 of a complete rotation.

But the angle is only half the story; we need to know the X and Y coordinate that the tip of the second hand is pointing at. How can we work that out?

Math

Imagine a circle with a radius of 1 drawn around the origin - the coordinate 0, 0.

This is called the 'unit circle' because... well, the radius is 1 unit!

The circumference of the circle is made of points on the grid - more coordinates. The x and y components of each of these coordinates form a triangle, the hypotenuse of which is always 1 - the radius of the circle

Now, trigonometry will let us work out the lengths of X and Y for each triangle if we know the angle they make with the origin. The X coordinate will be cos(a), and the Y coordinate will be sin(a), where a is the angle made between the line and the (positive) x axis.

(If you don't believe this, go and look at Wikipedia...)

One final twist - because we want to measure the angle from 12 o'clock rather than from the X axis (3 o'clock), we need to swap the axis around; now x = sin(a) and y = cos(a).

So now we know how to get the angle of the second hand (1/60th of a circle for each second) and the X and Y coordinates. We'll need functions for both sin and cos.

`math`

Happily the Go math package has both, with one small snag we'll need to get our heads around; if we look at the description of math.Cos:

Cos returns the cosine of the radian argument x.

It wants the angle to be in radians. Great. So what's a radian?

Instead of defining the full turn of a circle to be made up of 360 degrees, we define a full turn as being 2π radians. There are good reasons to do this that we won't go in to.¹

Now that we've done some reading, some learning and some thinking, we can write
our next test.

Write the test first

All this maths is hard and confusing. I'm not confident I understand what's going on - so let's write a test! We don't need to solve the whole problem in one go - let's start off with working out the correct angle, in radians, for the second hand at a particular time.

I'm going to write these tests within the clockface package; they may never get exported, and they may get deleted (or moved) once I have a better grip on what's going on.

I'm also going to comment out the acceptance test that I was working on while I'm working on these tests - I don't want to get distracted by that test while I'm getting this one to pass.

package clockface

import (
    "math"
    "testing"
    "time"
)

func TestSecondsInRadians(t *testing.T) {
    thirtySeconds := time.Date(312, time.October, 28, 0, 0, 30, 0, time.UTC)
    want := math.Pi
    got := secondsInRadians(thirtySeconds)

    if want != got {
        t.Fatalf("Wanted %v radians, but got %v", want, got)
    }
}

Here we're testing that 30 seconds past the minute should put the second hand at halfway around the clock. And it's our first use of the math package! If a full turn of a circle is 2π radians, we know that halfway round should just be π radians. math.Pi provides us with a value for π.

Try to run the test

# github.com/gypsydave5/learn-go-with-tests/math/v2/clockface [github.com/gypsydave5/learn-go-with-tests/math/v2/clockface.test]
./clockface_test.go:12:9: undefined: secondsInRadians
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v2/clockface [build failed]

Write the minimal amount of code for the test to run and check the failing test output

func secondsInRadians(t time.Time) float64 {
    return 0
}

--- FAIL: TestSecondsInRadians (0.00s)
    clockface_test.go:15: Wanted 3.141592653589793 radians, but got 0
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v2/clockface 0.007s

Write enough code to make it pass

func secondsInRadians(t time.Time) float64 {
    return math.Pi
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v2/clockface 0.011s

Refactor

Nothing needs refactoring yet

Repeat for new requirements

Now we can extend the test to cover a few more scenarios. I'm going to skip forward a bit and show some already refactored test code - it should be clear enough how I got where I want to.

func TestSecondsInRadians(t *testing.T) {
    cases := []struct {
        time  time.Time
        angle float64
    }{
        {simpleTime(0, 0, 30), math.Pi},
        {simpleTime(0, 0, 0), 0},
        {simpleTime(0, 0, 45), (math.Pi / 2) * 3},
        {simpleTime(0, 0, 7), (math.Pi / 30) * 7},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := secondsInRadians(c.time)
            if got != c.angle {
                t.Fatalf("Wanted %v radians, but got %v", c.angle, got)
            }
        })
    }
}

I added a couple of helper functions to make writing this table based test a little less tedious. testName converts a time into a digital watch format (HH:MM:SS), and simpleTime constructs a time.Time using only the parts we actually care about (again, hours, minutes and seconds).²

func simpleTime(hours, minutes, seconds int) time.Time {
    return time.Date(312, time.October, 28, hours, minutes, seconds, 0, time.UTC)
}

func testName(t time.Time) string {
    return t.Format("15:04:05")
}

These two functions should help make these tests (and future tests) a little easier to write and maintain.

This gives us some nice test output:

--- FAIL: TestSecondsInRadians (0.00s)
    --- FAIL: TestSecondsInRadians/00:00:00 (0.00s)
        clockface_test.go:24: Wanted 0 radians, but got 3.141592653589793
    --- FAIL: TestSecondsInRadians/00:00:45 (0.00s)
        clockface_test.go:24: Wanted 4.71238898038469 radians, but got 3.141592653589793
    --- FAIL: TestSecondsInRadians/00:00:07 (0.00s)
        clockface_test.go:24: Wanted 0.7330382858376184 radians, but got 3.141592653589793
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v3/clockface 0.007s

Time to implement all of that maths stuff we were talking about above:

func secondsInRadians(t time.Time) float64 {
    return float64(t.Second()) * (math.Pi / 30)
}

One second is (2π / 60) radians... cancel out the 2 and we get π/30 radians. Multiply that by the number of seconds (as a float64) and we should now have all the tests passing...

--- FAIL: TestSecondsInRadians (0.00s)
    --- FAIL: TestSecondsInRadians/00:00:30 (0.00s)
        clockface_test.go:24: Wanted 3.141592653589793 radians, but got 3.1415926535897936
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v3/clockface 0.006s

Wait, what?

Floats are horrible

Floating point arithmetic is notoriously inaccurate. Computers can only really handle integers, and rational numbers to some extent. Decimal numbers start to become inaccurate, especially when we factor them up and down as we are in the secondsInRadians function. By dividing math.Pi by 30 and then by multiplying it by 30 we've ended up with a number that's no longer the same as math.Pi.

There are two ways around this:

Live with the it
Refactor our function by refactoring our equation

Now (1) may not seem all that appealing, but it's often the only way to make floating point equality work. Being inaccurate by some infinitessimal fraction is frankly not going to matter for the purposes of drawing a clockface, so we could write a function that defines a 'close enough' equality for our angles. But there's a simple way we can get the accuracy back: we rearrange the equation so that we're no longer dividing down and then multiplying up. We can do it all by just dividing.

So instead of

numberOfSeconds * π / 30

we can write

π / (30 / numberOfSeconds)

which is equivalent.

In Go:

func secondsinradians(t time.time) float64 {
    return (math.Pi / (30 / (float64(t.Second()))))
}

And we get a pass.

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v2/clockface     0.005s

Repeat for new requirements

So we've got the first part covered here - we know what angle the second hand will be pointing at in radians. Now we need to work out the coordinates.

Again, let's keep this as simple as possible and only work with the unit circle; the circle with a radius of 1. This means that our hands will all have a length of one but, on the bright side, it means that the maths will be easy for us to swallow.

Write the test first

func TestSecondHandVector(t *testing.T) {
    cases := []struct {
        time  time.Time
        point Point
    }{
        {simpleTime(0, 0, 30), Point{0, -1}},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := secondHandPoint(c.time)
            if got != c.point {
                t.Fatalf("Wanted %v Point, but got %v", c.point, got)
            }
        })
    }
}

Try to run the test

# github.com/gypsydave5/learn-go-with-tests/math/v4/clockface [github.com/gypsydave5/learn-go-with-tests/math/v4/clockface.test]
./clockface_test.go:40:11: undefined: secondHandPoint
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v4/clockface [build failed]

Write the minimal amount of code for the test to run and check the failing test output

func secondHandPoint(t time.Time) Point {
    return Point{}
}

--- FAIL: TestSecondHandPoint (0.00s)
    --- FAIL: TestSecondHandPoint/00:00:30 (0.00s)
        clockface_test.go:42: Wanted {0 -1} Point, but got {0 0}
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v4/clockface 0.010s

Write enough code to make it pass

func secondHandPoint(t time.Time) Point {
    return Point{0, -1}
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v4/clockface 0.007s

Repeat for new requirements

func TestSecondHandPoint(t *testing.T) {
    cases := []struct {
        time  time.Time
        point Point
    }{
        {simpleTime(0, 0, 30), Point{0, -1}},
        {simpleTime(0, 0, 45), Point{-1, 0}},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := secondHandPoint(c.time)
            if got != c.point {
                t.Fatalf("Wanted %v Point, but got %v", c.point, got)
            }
        })
    }
}

Try to run the test

--- FAIL: TestSecondHandPoint (0.00s)
    --- FAIL: TestSecondHandPoint/00:00:45 (0.00s)
        clockface_test.go:43: Wanted {-1 0} Point, but got {0 -1}
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v4/clockface 0.006s

Write enough code to make it pass

Remember our unit circle picture?

We now want the equation that produces X and Y. Let's write it into seconds:

func secondHandPoint(t time.Time) Point {
    angle := secondsInRadians(t)
    x := math.Sin(angle)
    y := math.Cos(angle)

    return Point{x, y}
}

Now we get

--- FAIL: TestSecondHandPoint (0.00s)
    --- FAIL: TestSecondHandPoint/00:00:30 (0.00s)
        clockface_test.go:43: Wanted {0 -1} Point, but got {1.2246467991473515e-16 -1}
    --- FAIL: TestSecondHandPoint/00:00:45 (0.00s)
        clockface_test.go:43: Wanted {-1 0} Point, but got {-1 -1.8369701987210272e-16}
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v4/clockface 0.007s

Wait, what (again)? Looks like we've been cursed by the floats once more - both of those unexpected numbers are infinitessimal - way down at the 16th decimal place. So again we can either choose to try to increase precision, or to just say that they're roughly equal and get on with our lives.

One option to increase the accuracy of these angles would be to use the rational type Rat from the math/big package. But given the objective is to draw an SVG and not the moon landings I think we can live with a bit of fuzziness.

func TestSecondHandPoint(t *testing.T) {
    cases := []struct {
        time  time.Time
        point Point
    }{
        {simpleTime(0, 0, 30), Point{0, -1}},
        {simpleTime(0, 0, 45), Point{-1, 0}},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := secondHandPoint(c.time)
            if !roughlyEqualPoint(got, c.point) {
                t.Fatalf("Wanted %v Point, but got %v", c.point, got)
            }
        })
    }
}

func roughlyEqualFloat64(a, b float64) bool {
    const equalityThreshold = 1e-7
    return math.Abs(a-b) < equalityThreshold
}

func roughlyEqualPoint(a, b Point) bool {
    return roughlyEqualFloat64(a.X, b.X) &&
        roughlyEqualFloat64(a.Y, b.Y)
}

We've defined two functions to define approximate equality between two Points - they'll work if the X and Y elements are within 0.0000001 of each other. That's still pretty accurate.

And now we get

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v4/clockface 0.007s

Refactor

I'm still pretty happy with this.

Repeat for new requirements

Well, saying new isn't enirely accurate - really what we can do now is get that acceptance test passing! Let's remind ourselves of what it looks like:

func TestSecondHandAt30Seconds(t *testing.T) {
    tm := time.Date(1337, time.January, 1, 0, 0, 30, 0, time.UTC)

    want := clockface.Point{X: 150, Y: 150 + 90}
    got := clockface.SecondHand(tm)

    if got != want {
        t.Errorf("Got %v, wanted %v", got, want)
    }
}

Try to run the test

--- FAIL: TestSecondHandAt30Seconds (0.00s)
    clockface_acceptance_test.go:28: Got {150 60}, wanted {150 240}
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v5/clockface 0.007s

Write enough code to make it pass

We need to do three things to convert our unit vector into a point on the SVG:

Scale it to the length of the hand
Flip it over the X axis because to account for the SVG having an origin in the top left hand corner
Translate it to the right position (so that it's coming from an origin of (150,150))

Fun times!

// SecondHand is the unit vector of the second hand of an analogue clock at time `t`
// represented as a Point.
func SecondHand(t time.Time) Point {
    p := secondHandPoint(t)
    p = Point{p.X * 90, p.Y * 90}   // scale
    p = Point{p.X, -p.Y}            // flip
    p = Point{p.X + 150, p.Y + 150} // translate
    return p
}

Scale, flip, and translated in exactly that order. Hooray maths!

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v5/clockface 0.007s

Refactor

There's a few magic numbers here that should get pulled out as constants, so
let's do that

const secondHandLength = 90
const clockCentreX = 150
const clockCentreY = 150

// SecondHand is the unit vector of the second hand of an analogue clock at time `t`
// represented as a Point.
func SecondHand(t time.Time) Point {
    p := secondHandPoint(t)
    p = Point{p.X * secondHandLength, p.Y * secondHandLength}
    p = Point{p.X, -p.Y}
    p = Point{p.X + clockCentreX, p.Y + clockCentreY} //translate
    return p
}

Draw the clock

Well... the second hand anyway...

Let's do this thing - because there's nothing worse than not delivering some value when it's just sitting there waiting to get out into the world to dazzle people. Let's draw a second hand!

We're going to stick a new directory under our main clockface package directory, called (confusingly), clockface. In there we'll put the main package that will create the binary that will build an SVG:

├── clockface
│   └── main.go
├── clockface.go
├── clockface_acceptance_test.go
└── clockface_test.go

and inside main.go

package main

import (
    "fmt"
    "io"
    "os"
    "time"

    "github.com/gypsydave5/learn-go-with-tests/math/v6/clockface"
)

func main() {
    t := time.Now()
    sh := clockface.SecondHand(t)
    io.WriteString(os.Stdout, svgStart)
    io.WriteString(os.Stdout, bezel)
    io.WriteString(os.Stdout, secondHandTag(sh))
    io.WriteString(os.Stdout, svgEnd)
}

func secondHandTag(p clockface.Point) string {
    return fmt.Sprintf(`<line x1="150" y1="150" x2="%f" y2="%f" style="fill:none;stroke:#f00;stroke-width:3px;"/>`, p.X, p.Y)
}

const svgStart = `<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg"
     width="100%"
     height="100%"
     viewBox="0 0 300 300"
     version="2.0">`

const bezel = `<circle cx="150" cy="150" r="100" style="fill:#fff;stroke:#000;stroke-width:5px;"/>`

const svgEnd = `</svg>`

Oh boy am I not trying to win any prizes for beautiful code with this mess - but it does the job. It's writing an SVG out to os.Stdout - one string at a time.

If we build this

go build

and run it, sending the output into a file

./clockface > clock.svg

We should see something like

Refactor

This stinks. Well, it doesn't quite stink stink, but I'm not happy about it.

That whole SecondHand function is super tied to being an SVG... without mentioning SVGs or actually producing an SVG...
... while at the same time I'm not testing any of my SVG code.

Yeah, I guess I screwed up. This feels wrong. Let's try and recover with a more SVG-centric test.

What are our options? Well, we could try testing that the characters spewing out of the SVGWriter contain things that look like the sort of SVG tag we're expecting for a particular time. For instance:

func TestSVGWriterAtMidnight(t *testing.T) {
    tm := time.Date(1337, time.January, 1, 0, 0, 0, 0, time.UTC)

    var b strings.Builder
    clockface.SVGWriter(&b, tm)
    got := b.String()

    want := `<line x1="150" y1="150" x2="150" y2="60"`

    if !strings.Contains(got, want) {
        t.Errorf("Expected to find the second hand %v, in the SVG output %v", want, got)
    }
}

But is this really an improvement?

Not only will it still pass if I don't produce a valid SVG (as it's only testing that a string appears in the output), but it will also fail if I make the smallest, unimportant change to that string - if I add an extra space between the attributes, for instance.

The biggest smell is really that I'm testing a data structure - XML - by looking at its representation as a series of characters - as a string. This is never, ever a good idea as it produces problems just like the ones I outline above: a test that's both too fragile and not sensitive enough. A test that's testing the wrong thing!

So the only solution is to test the output as XML. And to do that we'll need
to parse it.

Parsing XML

encoding/xml is the Go package that can handle all things to do with
simple XML parsing.

The function xml.Unmarshall takes
a []byte of XML data and a pointer to a struct for it to get unmarshalled in
to.

So we'll need a struct to unmarshall our XML into. We could spend some time
working out what the correct names for all of the nodes and attributes, and how
to write the correct structure but, happily, someone has written
zek a program that will automate all of that
hard work for us. Even better, there's an online version at
https://www.onlinetool.io/xmltogo/. Just
paste the SVG from the top of the file into one box and - bam

out pops:

type Svg struct {
    XMLName xml.Name `xml:"svg"`
    Text    string   `xml:",chardata"`
    Xmlns   string   `xml:"xmlns,attr"`
    Width   string   `xml:"width,attr"`
    Height  string   `xml:"height,attr"`
    ViewBox string   `xml:"viewBox,attr"`
    Version string   `xml:"version,attr"`
    Circle  struct {
        Text  string `xml:",chardata"`
        Cx    string `xml:"cx,attr"`
        Cy    string `xml:"cy,attr"`
        R     string `xml:"r,attr"`
        Style string `xml:"style,attr"`
    } `xml:"circle"`
    Line []struct {
        Text  string `xml:",chardata"`
        X1    string `xml:"x1,attr"`
        Y1    string `xml:"y1,attr"`
        X2    string `xml:"x2,attr"`
        Y2    string `xml:"y2,attr"`
        Style string `xml:"style,attr"`
    } `xml:"line"`
}

We could make adjustments to this if we needed to (like changing the name of the
struct to SVG) but it's definitely good enough to start us off.

func TestSVGWriterAtMidnight(t *testing.T) {
    tm := time.Date(1337, time.January, 1, 0, 0, 0, 0, time.UTC)

    b := bytes.Buffer{}
    clockface.SVGWriter(&b, tm)

    svg := Svg{}
    xml.Unmarshal(b.Bytes(), &svg)

    x2 := "150"
    y2 := "60"

    for _, line := range svg.Line {
        if line.X2 == x2 && line.Y2 == y2 {
            return
        }
    }

    t.Errorf("Expected to find the second hand with x2 of %+v and y2 of %+v, in the SVG output %v", x2, y2, b.String())
}

We write the output of clockface.SVGWriter to a bytes.Buffer and then Unmarshall it into an Svg. We then look at each Line in the Svg to see if any of them have the expected X2 and Y2 values. If we get a match we return early (passing the test); if not we fail with a (hopefully) informative message.

# github.com/gypsydave5/learn-go-with-tests/math/v7b/clockface_test [github.com/gypsydave5/learn-go-with-tests/math/v7b/clockface.test]
./clockface_acceptance_test.go:41:2: undefined: clockface.SVGWriter
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v7b/clockface [build failed]

Looks like we'd better write that SVGWriter...

package clockface

import (
    "fmt"
    "io"
    "time"
)

const (
    secondHandLength = 90
    clockCentreX     = 150
    clockCentreY     = 150
)

//SVGWriter writes an SVG representation of an analogue clock, showing the time t, to the writer w
func SVGWriter(w io.Writer, t time.Time) {
    io.WriteString(w, svgStart)
    io.WriteString(w, bezel)
    secondHand(w, t)
    io.WriteString(w, svgEnd)
}

func secondHand(w io.Writer, t time.Time) {
    p := secondHandPoint(t)
    p = Point{p.X * secondHandLength, p.Y * secondHandLength} // scale
    p = Point{p.X, -p.Y}                                      // flip
    p = Point{p.X + clockCentreX, p.Y + clockCentreY}         // translate
    fmt.Fprintf(w, `<line x1="150" y1="150" x2="%.3f" y2="%.3f" style="fill:none;stroke:#f00;stroke-width:3px;"/>`, p.X, p.Y)
}

const svgStart = `<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg xmlns="http://www.w3.org/2000/svg"
     width="100%"
     height="100%"
     viewBox="0 0 300 300"
     version="2.0">`

const bezel = `<circle cx="150" cy="150" r="100" style="fill:#fff;stroke:#000;stroke-width:5px;"/>`

const svgEnd = `</svg>`

The most beautiful SVG writer? No. But hopefully it'll do the job...

--- FAIL: TestSVGWriterAtMidnight (0.00s)
    clockface_acceptance_test.go:56: Expected to find the second hand with x2 of 150 and y2 of 60, in the SVG output <?xml version="1.0" encoding="UTF-8" standalone="no"?>
        <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
        <svg xmlns="http://www.w3.org/2000/svg"
             width="100%"
             height="100%"
             viewBox="0 0 300 300"
             version="2.0"><circle cx="150" cy="150" r="100" style="fill:#fff;stroke:#000;stroke-width:5px;"/><line x1="150" y1="150" x2="150.000000" y2="60.000000" style="fill:none;stroke:#f00;stroke-width:3px;"/></svg>
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v7b/clockface    0.008s

Oooops! The %f format directive is printing our coordinates to the default level of precision - six decimal places. We should be explicit as to what level of precision we're expecting for the coordinates. Let's say three decimal places.

s := fmt.Sprintf(`<line x1="150" y1="150" x2="%.3f" y2="%.3f" style="fill:none;stroke:#f00;stroke-width:3px;"/>`, p.X, p.Y)

And after we update our expectations in the test

    x2 := "150.000"
    y2 := "60.000"

We get:

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v7b/clockface    0.006s

We can now shorten our main function:

package main

import (
    "os"
    "time"

    "github.com/gypsydave5/learn-go-with-tests/math/v7b/clockface"
)

func main() {
    t := time.Now()
    clockface.SVGWriter(os.Stdout, t)
}

And we can write a test for another time following the same pattern, but not before...

Refactor

Three things stick out:

We're not really testing for all of the information we need to ensure is present - what about the x1 values, for instance?
Also, those attributes for x1 etc. aren't really strings are they? They're numbers!
Do I really care about the style of the hand? Or, for that matter, the empty Text node that's been generated by zak?

We can do better. Let's make a few adjustments to the Svg struct, and the tests, to sharpen everything up.

type SVG struct {
    XMLName xml.Name `xml:"svg"`
    Xmlns   string   `xml:"xmlns,attr"`
    Width   float64  `xml:"width,attr"`
    Height  float64  `xml:"height,attr"`
    ViewBox string   `xml:"viewBox,attr"`
    Version string   `xml:"version,attr"`
    Circle  Circle   `xml:"circle"`
    Line    []Line   `xml:"line"`
}

type Circle struct {
    Cx float64 `xml:"cx,attr"`
    Cy float64 `xml:"cy,attr"`
    R  float64 `xml:"r,attr"`
}

type Line struct {
    X1 float64 `xml:"x1,attr"`
    Y1 float64 `xml:"y1,attr"`
    X2 float64 `xml:"x2,attr"`
    Y2 float64 `xml:"y2,attr"`
}

Here I've

Made the important parts of the struct named types -- the Line and the Circle
Turned the numeric attributes into float64s instead of strings.
Deleted unused attributes like Style and Text
Renamed Svg to SVG because it's the right thing to do.

This will let us assert more precisely on the line we're looking for:

func TestSVGWriterAtMidnight(t *testing.T) {
    tm := time.Date(1337, time.January, 1, 0, 0, 0, 0, time.UTC)
    b := bytes.Buffer{}

    clockface.SVGWriter(&b, tm)

    svg := SVG{}

    xml.Unmarshal(b.Bytes(), &svg)

    want := Line{150, 150, 150, 60}

    for _, line := range svg.Line {
        if line == want {
            return
        }
    }

    t.Errorf("Expected to find the second hand line %+v, in the SVG lines %+v", want, svg.Line)
}

Finally we can take a leaf out of the unit tests' tables, and we can write a helper function containsLine(line Line, lines []Line) bool to really make these tests shine:

func TestSVGWriterSecondHand(t *testing.T) {
    cases := []struct {
        time time.Time
        line Line
    }{
        {
            simpleTime(0, 0, 0),
            Line{150, 150, 150, 60},
        },
        {
            simpleTime(0, 0, 30),
            Line{150, 150, 150, 240},
        },
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            b := bytes.Buffer{}
            clockface.SVGWriter(&b, c.time)

            svg := SVG{}
            xml.Unmarshal(b.Bytes(), &svg)

            if !containsLine(c.line, svg.Line) {
                t.Errorf("Expected to find the second hand line %+v, in the SVG lines %+v", c.line, svg.Line)
            }
        })
    }
}

Now that's what I call an acceptance test!

Write the test first

So that's the second hand done. Now let's get started on the minute hand.

func TestSVGWriterMinutedHand(t *testing.T) {
    cases := []struct {
        time time.Time
        line Line
    }{
        {
            simpleTime(0, 0, 0),
            Line{150, 150, 150, 70},
        },
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            b := bytes.Buffer{}
            clockface.SVGWriter(&b, c.time)

            svg := SVG{}
            xml.Unmarshal(b.Bytes(), &svg)

            if !containsLine(c.line, svg.Line) {
                t.Errorf("Expected to find the minute hand line %+v, in the SVG lines %+v", c.line, svg.Line)
            }
        })
    }
}

Try to run the test

--- FAIL: TestSVGWriterMinutedHand (0.00s)
    --- FAIL: TestSVGWriterMinutedHand/00:00:00 (0.00s)
        clockface_acceptance_test.go:87: Expected to find the minute hand line {X1:150 Y1:150 X2:150 Y2:70}, in the SVG lines [{X1:150 Y1:150 X2:150 Y2:60}]
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v8/clockface 0.007s

We'd better start building some other clockhands, Much in the same way as we produced the tests for the second hand, we can iterate to produce the following set of tests. Again we'll comment out our acceptance test while we get this working:

func TestMinutesInRadians(t *testing.T) {
    cases := []struct {
        time  time.Time
        angle float64
    }{
        {simpleTime(0, 30, 0), math.Pi},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := minutesInRadians(c.time)
            if got != c.angle {
                t.Fatalf("Wanted %v radians, but got %v", c.angle, got)
            }
        })
    }
}

Try to run the test

# github.com/gypsydave5/learn-go-with-tests/math/v8/clockface [github.com/gypsydave5/learn-go-with-tests/math/v8/clockface.test]
./clockface_test.go:59:11: undefined: minutesInRadians
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v8/clockface [build failed]

Write the minimal amount of code for the test to run and check the failing test output

func minutesInRadians(t time.Time) float64 {
    return math.Pi
}

Repeat for new requirements

Well, OK - now let's make ourselves do some real work. We could model the minute hand as only moving every full minute - so that it 'jumps' from 30 to 31 minutes past without moving in between. But that would look a bit rubbish. What we want it to do is move a tiny little bit every second.

func TestMinutesInRadians(t *testing.T) {
    cases := []struct {
        time  time.Time
        angle float64
    }{
        {simpleTime(0, 30, 0), math.Pi},
        {simpleTime(0, 0, 7), 7 * (math.Pi / (30 * 60))},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := minutesInRadians(c.time)
            if got != c.angle {
                t.Fatalf("Wanted %v radians, but got %v", c.angle, got)
            }
        })
    }
}

How much is that tiny little bit? Well...

Sixty seconds in a minute
thirty minutes in a half turn of the circle (math.Pi radians)
so 30 * 60 seconds in a half turn.
So if the time is 7 seconds past the hour ...
... we're expecting to see the minute hand at 7 * (math.Pi / (30 * 60)) radians past the 12.

Try to run the test

--- FAIL: TestMinutesInRadians (0.00s)
    --- FAIL: TestMinutesInRadians/00:00:07 (0.00s)
        clockface_test.go:62: Wanted 0.012217304763960306 radians, but got 3.141592653589793
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v8/clockface 0.009s

Write enough code to make it pass

In the immortal words of Jennifer Aniston: Here comes the science bit

func minutesInRadians(t time.Time) float64 {
    return (secondsInRadians(t) / 60) +
        (math.Pi / (30 / float64(t.Minute())))
}

Rather than working out how far to push the minute hand around the clockface for every second from scratch, here we can just leverage the secondsInRadians function. For every second the minute hand will move 1/60th of the angle the second hand moves.

secondsInRadians(t) / 60

Then we just add on the movement for the minutes - similar to the movement of the second hand.

math.Pi / (30 / float64(t.Minute()))

And...

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v8/clockface 0.007s

Nice and easy.

Repeat for new requirements

Should I add more cases to the minutesInRadians test? At the moment there are only two. How many cases do I need before I move on to the testing the minuteHandPoint function?

One of my favourite TDD quotes, often attributed to Kent Beck,³ is

Write tests until fear is transformed into boredom.

And, frankly, I'm bored of testing that function. I'm confident I know how it works. So it's on to the next one.

Write the test first

func TestMinuteHandPoint(t *testing.T) {
    cases := []struct {
        time  time.Time
        point Point
    }{
        {simpleTime(0, 30, 0), Point{0, -1}},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := minuteHandPoint(c.time)
            if !roughlyEqualPoint(got, c.point) {
                t.Fatalf("Wanted %v Point, but got %v", c.point, got)
            }
        })
    }
}

Try to run the test

# github.com/gypsydave5/learn-go-with-tests/math/v9/clockface [github.com/gypsydave5/learn-go-with-tests/math/v9/clockface.test]
./clockface_test.go:79:11: undefined: minuteHandPoint
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v9/clockface [build failed]

Write the minimal amount of code for the test to run and check the failing test output

func minuteHandPoint(t time.Time) Point {
    return Point{}
}

--- FAIL: TestMinuteHandPoint (0.00s)
    --- FAIL: TestMinuteHandPoint/00:30:00 (0.00s)
        clockface_test.go:80: Wanted {0 -1} Point, but got {0 0}
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v9/clockface 0.007s

Write enough code to make it pass

func minuteHandPoint(t time.Time) Point {
    return Point{0, -1}
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v9/clockface 0.007s

Repeat for new requirements

And now for some actual work

func TestMinuteHandPoint(t *testing.T) {
    cases := []struct {
        time  time.Time
        point Point
    }{
        {simpleTime(0, 30, 0), Point{0, -1}},
        {simpleTime(0, 45, 0), Point{-1, 0}},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := minuteHandPoint(c.time)
            if !roughlyEqualPoint(got, c.point) {
                t.Fatalf("Wanted %v Point, but got %v", c.point, got)
            }
        })
    }
}

--- FAIL: TestMinuteHandPoint (0.00s)
    --- FAIL: TestMinuteHandPoint/00:45:00 (0.00s)
        clockface_test.go:81: Wanted {-1 0} Point, but got {0 -1}
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v9/clockface 0.007s

Write enough code to make it pass

A quick copy and paste of the secondHandPoint function with some minor changes ought to do it...

func minuteHandPoint(t time.Time) Point {
    angle := minutesInRadians(t)
    x := math.Sin(angle)
    y := math.Cos(angle)

    return Point{x, y}
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v9/clockface 0.009s

Refactor

We've definitely got a bit of repetition in the minuteHandPoint and secondHandPoint - I know because we just copied and pasted one to make the other. Let's DRY it out with a function.

func angleToPoint(angle float64) Point {
    x := math.Sin(angle)
    y := math.Cos(angle)

    return Point{x, y}
}

and we can rewrite minuteHandPoint and secondHandPoint as one liners:

func minuteHandPoint(t time.Time) Point {
    return angleToPoint(minutesInRadians(t))
}

func secondHandPoint(t time.Time) Point {
    return angleToPoint(secondsInRadians(t))
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v9/clockface 0.007s

Now we can uncomment the acceptance test and get to work drawing the minute hand

Write enough code to make it pass

Another quick copy-and-paste with some minor adjustments

func minuteHand(w io.Writer, t time.Time) {
    p := minuteHandPoint(t)
    p = Point{p.X * secondHandLength, p.Y * secondHandLength}
    p = Point{p.X, -p.Y}
    p = Point{p.X + clockCentreX, p.Y + clockCentreY}
    fmt.Fprintf(w, `<line x1="150" y1="150" x2="%.3f" y2="%.3f" style="fill:none;stroke:#000;stroke-width:3px;"/>`, p.X, p.Y)
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v9/clockface 0.006s

But the proof of the pudding is in the eating - if we now compile and run our clockface program, we should see something like

Refactor

Let's remove the duplication from the secondHand and minuteHand functions, putting all of that scale, flip and translate logic all in one place.

func secondHand(w io.Writer, t time.Time) {
    p := makeHand(secondHandPoint(t), secondHandLength)
    fmt.Fprintf(w, `<line x1="150" y1="150" x2="%.3f" y2="%.3f" style="fill:none;stroke:#f00;stroke-width:3px;"/>`, p.X, p.Y)
}

func minuteHand(w io.Writer, t time.Time) {
    p := makeHand(minuteHandPoint(t), minuteHandLength)
    fmt.Fprintf(w, `<line x1="150" y1="150" x2="%.3f" y2="%.3f" style="fill:none;stroke:#000;stroke-width:3px;"/>`, p.X, p.Y)
}

func makeHand(p Point, length float64) Point {
    p = Point{p.X * length, p.Y * length}
    p = Point{p.X, -p.Y}
    return Point{p.X + clockCentreX, p.Y + clockCentreY}
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v9/clockface 0.007s

There... now it's just the hour hand to do!

Write the test first

func TestSVGWriterHourHand(t *testing.T) {
    cases := []struct {
        time time.Time
        line Line
    }{
        {
            simpleTime(6, 0, 0),
            Line{150, 150, 150, 200},
        },
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            b := bytes.Buffer{}
            clockface.SVGWriter(&b, c.time)

            svg := SVG{}
            xml.Unmarshal(b.Bytes(), &svg)

            if !containsLine(c.line, svg.Line) {
                t.Errorf("Expected to find the minute hand line %+v, in the SVG lines %+v", c.line, svg.Line)
            }
        })
    }
}

Try to run the test

--- FAIL: TestSVGWriterHourHand (0.00s)
    --- FAIL: TestSVGWriterHourHand/06:00:00 (0.00s)
        clockface_acceptance_test.go:113: Expected to find the minute hand line {X1:150 Y1:150 X2:150 Y2:200}, in the SVG lines [{X1:150 Y1:150 X2:150 Y2:60} {X1:150 Y1:150 X2:150 Y2:70}]
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.013s

Again, let's comment this one out until we've got the some coverage with the
lower level tests:

Write the test first

func TestHoursInRadians(t *testing.T) {
    cases := []struct {
        time  time.Time
        angle float64
    }{
        {simpleTime(6, 0, 0), math.Pi},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := hoursInRadians(c.time)
            if got != c.angle {
                t.Fatalf("Wanted %v radians, but got %v", c.angle, got)
            }
        })
    }
}

Try to run the test

# github.com/gypsydave5/learn-go-with-tests/math/v10/clockface [github.com/gypsydave5/learn-go-with-tests/math/v10/clockface.test]
./clockface_test.go:97:11: undefined: hoursInRadians
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v10/clockface [build failed]

Write the minimal amount of code for the test to run and check the failing test output

func hoursInRadians(t time.Time) float64 {
    return math.Pi
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.007s

Repeat for new requirements

func TestHoursInRadians(t *testing.T) {
    cases := []struct {
        time  time.Time
        angle float64
    }{
        {simpleTime(6, 0, 0), math.Pi},
        {simpleTime(0, 0, 0), 0},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := hoursInRadians(c.time)
            if got != c.angle {
                t.Fatalf("Wanted %v radians, but got %v", c.angle, got)
            }
        })
    }
}

Try to run the test

--- FAIL: TestHoursInRadians (0.00s)
    --- FAIL: TestHoursInRadians/00:00:00 (0.00s)
        clockface_test.go:100: Wanted 0 radians, but got 3.141592653589793
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.007s

Write enough code to make it pass

func hoursInRadians(t time.Time) float64 {
    return (math.Pi / (6 / float64(t.Hour())))
}

Repeat for new requirements

func TestHoursInRadians(t *testing.T) {
    cases := []struct {
        time  time.Time
        angle float64
    }{
        {simpleTime(6, 0, 0), math.Pi},
        {simpleTime(0, 0, 0), 0},
        {simpleTime(21, 0, 0), math.Pi * 1.5},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := hoursInRadians(c.time)
            if got != c.angle {
                t.Fatalf("Wanted %v radians, but got %v", c.angle, got)
            }
        })
    }
}

Try to run the test

--- FAIL: TestHoursInRadians (0.00s)
    --- FAIL: TestHoursInRadians/21:00:00 (0.00s)
        clockface_test.go:101: Wanted 4.71238898038469 radians, but got 10.995574287564276
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.014s

Write enough code to make it pass

func hoursInRadians(t time.Time) float64 {
    return (math.Pi / (6 / (float64(t.Hour() % 12))))
}

Remember, this is not a 24 hour clock; we have to use the remainder operator to get the remainder of the current hour divided by 12.

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.008s

Write the test first

Now let's try and move the hour hand around the clocface based on the minutes and the seconds that have passed.

func TestHoursInRadians(t *testing.T) {
    cases := []struct {
        time  time.Time
        angle float64
    }{
        {simpleTime(6, 0, 0), math.Pi},
        {simpleTime(0, 0, 0), 0},
        {simpleTime(21, 0, 0), math.Pi * 1.5},
        {simpleTime(0, 1, 30), math.Pi / ((6 * 60 * 60) / 90)},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := hoursInRadians(c.time)
            if got != c.angle {
                t.Fatalf("Wanted %v radians, but got %v", c.angle, got)
            }
        })
    }
}

Try to run the test

--- FAIL: TestHoursInRadians (0.00s)
    --- FAIL: TestHoursInRadians/00:01:30 (0.00s)
        clockface_test.go:102: Wanted 0.013089969389957472 radians, but got 0
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.007s

Write enough code to make it pass

Again, a bit of thinking is now required. We need to move the hour hand along a little bit for both the minutes and the seconds. Luckily we have an angle already to hand for the minutes and the seconds - the one returned by minutesInRadians. We can reuse it!

So the only question is by what factor to reduce the size of that angle. One full turn is one hour for the minute hand, but for the hour hand it's twelve hours. So we just divide the angle returned by minutesInRadians by twelve:

func hoursInRadians(t time.Time) float64 {
    return (minutesInRadians(t) / 12) +
        (math.Pi / (6 / float64(t.Hour()%12)))
}

and behold:

--- FAIL: TestHoursInRadians (0.00s)
    --- FAIL: TestHoursInRadians/00:01:30 (0.00s)
        clockface_test.go:104: Wanted 0.013089969389957472 radians, but got 0.01308996938995747
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.007s

AAAAARGH BLOODY FLOATING POINT ARITHMETIC!

Let's update our test to use roughlyEqualFloat64 for the comparison of the
angles.

func TestHoursInRadians(t *testing.T) {
    cases := []struct {
        time  time.Time
        angle float64
    }{
        {simpleTime(6, 0, 0), math.Pi},
        {simpleTime(0, 0, 0), 0},
        {simpleTime(21, 0, 0), math.Pi * 1.5},
        {simpleTime(0, 1, 30), math.Pi / ((6 * 60 * 60) / 90)},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := hoursInRadians(c.time)
            if !roughlyEqualFloat64(got, c.angle) {
                t.Fatalf("Wanted %v radians, but got %v", c.angle, got)
            }
        })
    }
}

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.007s

Refactor

If we're going to use roughlyEqualFloat64 in one of our radians tests, we should probably use it for all of them. That's a nice and simple refactor.

Hour Hand Point

Right, it's time to calculate where the hour hand point is going to go by working out the unit vector.

Write the test first

func TestHourHandPoint(t *testing.T) {
    cases := []struct {
        time  time.Time
        point Point
    }{
        {simpleTime(6, 0, 0), Point{0, -1}},
        {simpleTime(21, 0, 0), Point{-1, 0}},
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            got := hourHandPoint(c.time)
            if !roughlyEqualPoint(got, c.point) {
                t.Fatalf("Wanted %v Point, but got %v", c.point, got)
            }
        })
    }
}

Wait, am I just going to throw two test cases out there at once? Isn't this bad TDD?

On TDD Zealotry

Test driven development is not a religion. Some people might act like it is - usually people who don't do TDD but who are happy to moan on Twitter or Dev.to that it's only done by zealots and that they're 'being pragmatic' when they don't write tests. But it's not a religion. It's tool.

I know what the two tests are going to be - I've tested two other clock hands in exactly the same way - and I already know what my implementation is going to be - I wrote a function for the general case of changing an angle into a point in the minute hand iteration.

I'm not going to plough through TDD ceremony for the sake of it. Tests are a tool to help me write better code. TDD is a technique to help me write better code. Neither tests nor TDD are an end in themselves.

My confidence has increased, so I feel I can make larger strides forward. I'm going to 'skip' a few steps, because I know where I am, I know where I'm going and I've been down this road before.

But also note: I'm not skipping writing the tests entirely.

Try to run the test

# github.com/gypsydave5/learn-go-with-tests/math/v11/clockface [github.com/gypsydave5/learn-go-with-tests/math/v11/clockface.test]
./clockface_test.go:119:11: undefined: hourHandPoint
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v11/clockface [build failed]

Write enough code to make it pass

func hourHandPoint(t time.Time) Point {
    return angleToPoint(hoursInRadians(t))
}

As I said, I know where I am and I know where I'm going. Why pretend otherwise? The tests will soon tell me if I'm wrong.

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v11/clockface    0.009s

Draw the hour hand

And finally we get to draw in the hour hand. We can bring in that acceptance test by uncommenting it:

func TestSVGWriterHourHand(t *testing.T) {
    cases := []struct {
        time time.Time
        line Line
    }{
        {
            simpleTime(6, 0, 0),
            Line{150, 150, 150, 200},
        },
    }

    for _, c := range cases {
        t.Run(testName(c.time), func(t *testing.T) {
            b := bytes.Buffer{}
            clockface.SVGWriter(&b, c.time)

            svg := SVG{}
            xml.Unmarshal(b.Bytes(), &svg)

            if !containsLine(c.line, svg.Line) {
                t.Errorf("Expected to find the minute hand line %+v, in the SVG lines %+v", c.line, svg.Line)
            }
        })
    }
}

Try to run the test

--- FAIL: TestSVGWriterHourHand (0.00s)
    --- FAIL: TestSVGWriterHourHand/06:00:00 (0.00s)
        clockface_acceptance_test.go:113: Expected to find the minute hand line {X1:150 Y1:150 X2:150 Y2:200}, in the SVG lines [{X1:150 Y1:150 X2:150 Y2:60} {X1:150 Y1:150 X2:150 Y2:70}]
FAIL
exit status 1
FAIL    github.com/gypsydave5/learn-go-with-tests/math/v10/clockface    0.013s

Write enough code to make it pass

And we can now make our final adjustments to svgWriter.go

const (
    secondHandLength = 90
    minuteHandLength = 80
    hourHandLength   = 50
    clockCentreX     = 150
    clockCentreY     = 150
)

//SVGWriter writes an SVG representation of an analogue clock, showing the time t, to the writer w
func SVGWriter(w io.Writer, t time.Time) {
    io.WriteString(w, svgStart)
    io.WriteString(w, bezel)
    secondHand(w, t)
    minuteHand(w, t)
    hourHand(w, t)
    io.WriteString(w, svgEnd)
}

// ...

func hourHand(w io.Writer, t time.Time) {
    p := makeHand(hourHandPoint(t), hourHandLength)
    fmt.Fprintf(w, `<line x1="150" y1="150" x2="%.3f" y2="%.3f" style="fill:none;stroke:#000;stroke-width:3px;"/>`, p.X, p.Y)
}

and so...

PASS
ok      github.com/gypsydave5/learn-go-with-tests/math/v12/clockface    0.007s

Let's just check by compiling and running our clockface program.

Refactor

Looking at clockface.go, there are a few 'magic numbers' floating about. They are all based around how many hours/minutes/seconds there are in a half-turn around a clockface. Let's refactor so that we make explicit their meaning.

const (
    secondsInHalfClock = 30
    secondsInClock     = 2 * secondsInHalfClock
    minutesInHalfClock = 30
    minutesInClock     = 2 * minutesInHalfClock
    hoursInHalfClock   = 6
    hoursInClock       = 2 * hoursInHalfClock
)

Why do this? Well, it makes explicit what each number means in the equation. If - when - we come back to this code, these names will help us to understand what's going on.

Moreover, should we ever want to make some really, really WEIRD clocks - ones with 4 hours for the hour hand, and 20 seconds for the second hand say - these constants could easily become parameters. We're helping to leave that door open (even if we never go through it).

Wrapping up

Do we need to do anything else?

First, let's pat ourselves on the back - we've written a program that makes an SVG clockface. It works and it's great. It will only ever make one sort of clockface - but that's fine! Maybe you only want one sort of clockface. There's nothing wrong with a program that solves a specific problem and nothing else.

A Program... and a Library

But the code we've written does solve a more general set of problems to do with drawing a clockface. Because we used tests to think about each small part of the problem in isolation, and because we codified that isolation with functions, we've built a very reasonable little API for clockface calculations.

We can work on this project and turn it into something more general - a library for calculating clockface angles and/or vectors.

In fact, providing the library along with the program is a really good idea. It costs us nothing, while increasing the utility of our program and helping to document how it works.

APIs should come with programs, and vice versa. An API that you must write C code to use, which cannot be invoked easily from the command line, is harder to learn and use. And contrariwise, it's a royal pain to have interfaces whose only open, documented form is a program, so you cannot invoke them easily from a C program.
-- Henry Spencer, in The Art of Unix Programming

In my final take on this program, I've made the unexported functions within clockface into a public API for the library, with functions to calculate the angle and unit vector for each of the clock hands. I've also split the SVG generation part into its own package, svg, which is then used by the clockface program directly. Naturally I've documented each of the functions and packages.

Talking about SVGs...

The Most Valuable Test

I'm sure you've noticed that the most sophisticated piece of code for handling SVGs isn't in our application code at all; it's in the test code. Should this make us feel uncomfortable? Shouldn't we do something like

use a template from text/template?
use an XML library (much as we're doing in our test)?
use an SVG library?

We could refactor our code to do any of these things, and we can do so because because it doesn't matter how we produce our SVG, what's important is that it's an SVG that we produce. As such, the part of our system that needs to know the most about SVGs - that needs to be the strictest about what constitutes an SVG - is the test for the SVG output; it needs to have enough context and knowledge about SVGs for us to be confident that we're outputting an SVG.

We may have felt odd that we were pouring a lot of time and effort into those SVG tests - importing an XML library, parsing XML, refactoring the structs - but that test code is a valuable part of our codebase - possibly more valuable than the current production code. It will help guarantee that the output is always a valid SVG, no matter what we choose to use to produce it.

Tests are not second class citizens - they are not 'throwaway' code. Good tests will last a lot longer than the particular version of the code they are testing. You should never feel like you're spending 'too much time' writing your tests. It's usually a wise investment.

Cover image by the extremely talented Denise Yu, who drew it for the book. Ask her if you're allowed to use it.

In short it makes it easier to do calculus with circles as π just keeps coming up as an angle if you use normal degrees, so if you count your angles in πs it makes all the equations simpler. ↩
This is a lot easier than writing a name out by hand as a string and then having to keep it in sync with the actual time. Believe me you don't want to do that... ↩
Missattributed because, like all great authors, Kent Beck is more quoted than read. Beck himself attributes it to Phlip. ↩

On Developer Fetishes

David Wickes — Mon, 15 Jul 2019 22:18:42 +0000

Caveat Lector

What follows is more of a stream of consciousneess that fell out a few nights ago pretty much unedited and very unpolished. Please don't take it too seriously, or personally (that would be too ironic) - it's as much directed at me as it is anyone. I'm publishing it with regret.

Programming languages do not care about you

You love your language. You've spent hours, days - months - learning its intricacies inside out. You are the grand wizard of JavaScript. You are the shining Ruby of Rubyists. You are the P in PHP, the Hoss of Haskell, the rustiest Rustacean, the goofiest Gopher, the biggest, steamiest, hottest cup of Java in the JVM shop.

So what.

Your language is really just a set of blinkers around what you can do. You are ultimately limited by your language; trust me, it cannot do everything you want it to do.

What's vital for a language isn't the language - its features, its warts, its amazing syntax for one line anonymous function calls, or array destructuring, or pattern matching...

Or its beautiful landing page, its cod philosophy, its ridiculously cute rodent mascot.

It's not even what it teaches you, about the world and about computers. That's important, and useful, but it isn't the most important thing.

The most important thing about a language is the people who speak it and the problems they solve with it. Try to keep it that way.

You are not the framework you use

If it's true for languages, it's doubly true for frameworks. But it's usually these artefacts that are the cause of the greatest and most vociferous developer fetishism - yes, I'm talking to you, front end JavaScript developers of 2019.

Nobody cares if your website is made in React. Or Angular. Or Vue. Or Preact. Or Bumfle. You haven't heard of Bumfle? I just made it up. My website is written in Bumfle. It's the best. I'm a Bumfle developer. Been one for the past twenty seconds. I'm the best at Bumfle. Please sign up for my free Bumfle training course. We in the Bumfle community welcome all Bumfle contributors. Also, I've just changed the Bumfle API to use Bumfle hooks which I'm calling Books. Saga Books now because I've read the DDD book. All your Bumfle code is now broken because of this. You are welcome. Also, Bumfle is now called Fumble. Also I'm now building the next Fumble. It's called Brian.

Nobody cares if you love a framework more than the last version of React, or whether it is simpler or easier to use than the next version of Vue. Especially not the framework.

Because in two minutes time the subject of all your passion and effort and love and time will evaporate through the whimsy of a maintainer, an exciting change in fashion, an update to 3.6.6.6, a new API that introduces every other term from the DDD book...

(Bumfle objects are now called Baggregates. You are welcome.)

Do not get attached to a framework. Do not fall in love with these ephemera. The most important thing a framework can do is solve particular problem. Try and solve more problems, stop finding problems to solve with your favourite magic box. Stop inventing problems to solve with your favourite magic box.

Your text editor does not define you

Vim is fun. You feel like you've passed a small exam every time you remember a command correctly. You get a small dopamine hit. You are a successful individual and a powerful software developer. At least a 5X. You must be because you know how to delete a word. You then want to tell your friends about your huge triumph in writing a macro that adds a comma to the end of each line.

Try and suppress this desire. Maybe suck on something sugary for five minutes instead. It will pass.

Who cares how quickly you can delete a word? Or a line? Or cut and paste a paragraph? Is the speed at which you can surround a single word with quotation marks really the limiting factor on your work? You were unable to write your algorithm because it took you too long to do the copying and pasting? Your startup failed because you weren't typing fast enough? Really?

All those plugins - this goes for the VS Code people too - do you use them? They seemed like a good idea when you installed them. Free stuff. But do you ever use them? Are they just filling your screen with more noise? Was it worth spending those three hours choosing the right colour scheme?

Take a good, long, hard look at what you actually do when you write code. Is there really that much that you're doing that couldn't be achieved with Windows Notepad?

Your text editor is just another tool. It's a means to an end. It is not a status symbol. If you're spending more than one percent of your time setting up an editor... stop.

Your terminal does not express your individuality

The perfect font. The perfect colour scheme. The perfect shell.

Bash of course. No, not bash. Nobody uses bash any more. Who are you. Get out of here. No, we use zsh. No, we don't know how to pronounce it either. But we use it. Or fish. Or something else. It's amazing.

We use tmux. Mainly so we can see a big clock. We have a custom prompt. It tells us how many minutes until our JavaScript framework becomes obsolete. We have a terminal emulator that emits fireworks as we type. With a black background. Because we are 10x developers and it's just like Mr. Robot.

Stop. Please. It's a terminal. It's a shell. You can spend a month customising it and in the end you'll not be a better developer. You'll just hate the look of whatever abomination you've created and spend another month making it better. And another. And another...

Stop worrying about how it looks and just use it. To do some development. You know. What you were meant to be doing.

Solutions

I've been told that just moaning about all of this stuff without supplying any solutions isn't very nice. So I'll try and be nicer.

Languages. Learn more than one. Learn more than two. Travel broadens the mind. You will learn to love your first language more. You will be forced to think of new ways of solving old problems. You will understand computers better. When you talk about languages, talk about how they differ and how it's nice to do things in different ways. Caveat: don't just learn how to write hello world in twenty languages; learn a handful of distinct ones to a good degree. This is not a waste of time.
Frameworks. If your framework isn't giving you skills and knowledge you can transfer to the real world, I'd worry. Make sure you know how it works 'under the hood'. Don't get trapped. Every framework is a sinking ship. Every single one. And, yes, we are all rats. Don't learn more than one at a time. Forget everything you can about it when it finally dumps you.
Editors. This isn't so much advice as some ideas. Delete your plugins, turn off syntax highlighting, and give it a week. Find ways of using your skill at programming (you're a programmer, right?) to extend your editor by using its interactions with the shell. Try changing editors for a month to try something else. Try using ed for a week.
Terminals. Use the out of the box settings for whatever computer you're using and wait until you can't do something you need to do before you start messing with it. Exception: you may have a dark background if you do all your work in a pitch black room. But maybe ask yourself why you're doing all your coding in a pitch black room. Are you OK? Would you like to talk to someone?

Cover Image: The Golden Calf by Herrad of Landsberg

The Cake Mix Metaphor for Frameworks

David Wickes — Sun, 14 Jul 2019 21:48:14 +0000

A great video was brought to my attention on Twitter recently. It's a lightning talk by @CristinGorman that she gave at JavaZone in 2011.

The title is

Hibernate should be to programmers what cake mixes are to bakers: beneath their dignity.

which is pretty punchy.

Hibernate, for those of you lucky enough to never have used it, is a 'library' for interacting with relational databases in Java.

It reminded me of my own rant

Why You Shouldn't Use A Web Framework

David Wickes ・ Jul 26 '18

#webdev #framework #beginners #react

And I wish I'd seen it a long time ago. The cake mix metaphor is outstanding - it expresses exactly what I've been trying to say about frameworks. But better, because it's baking.

Something to chew on...

Image credit: The Gathering of the Manna, by The Master of The Gathering of the Manna.

If you're ever feeling under appreciated, consider that even those of us who can produce artworks that last over five centuries have become anonymous...

Front End: Is Anything Getting Better?

David Wickes — Sun, 23 Jun 2019 15:06:34 +0000

It's been around nine years since Angular JS (the first one) was unleashed on the world. Nine years of single page apps (SPAs) in the browser, and constant innovation in the frameworks used to build them.

Dev.to has a great community of active, intelligent and helpful frontend developers who use a variety of frameworks to build SPAs. Perhaps some of them have been working in this area since the first Angular JS came out.

My question to anyone who's interested: is anything getting better?

Is it getting better for the users of our SPAs. What has improved for them in the last nine years - think of specific things. If you don't think it has improved, tell me - why not?

Is it getting better for the developers of SPAs? Is it easier today to build, say, a todo app than it was nine years ago?

Dark Side vs Light Side

David Wickes — Tue, 23 Apr 2019 21:05:15 +0000

Tell me, Dev.to - do you use a dark background in your editor and terminal, or a light background? And now tell me - why?

(Maybe it's neither. Maybe you're like the frontend dev who sits two desks in front of me at work and it's a BRIGHT RED background in his terminal. All the time. Every day. It hurts my eyes from 10 meters away. What a hero.)

Why learn... about Media Types

David Wickes — Wed, 10 Apr 2019 22:56:11 +0000

Media types are used to communicate the type of data being sent over the web. They are used

in an HTTP response to declare the type of content being sent
in requests to declare what sort of content the client can interpret
in POST requests to declare the type of content being sent.

Basically, wherever there is data on the web, there will be a media type to tell you what sort of data it is. And if there's not, well there really ought to be.

This article will explain how to interpret a media type and also explain how they are used in HTTP headers to make sure we get the data that we can understand.

Who is this for?
Where Have I seen Media Types Before?
Media Type Syntax
Media Types in HTTP Message Headers
Content Negotiation
Roll Your Own Media Type
Summary
Q and A

Who is this for?

This is for web developers who are interested in understanding how to move data over the web. Some knowledge of HTTP, specifically headers, is useful but not necessary.

Where Have I Seen Media Types Before?

The first time I saw a media type was when I wrote my first HTML file - specifically to get some CSS:¹

<link rel="stylesheet" src="style.css" type="text/css" />

There's our first media type - text/css.

The next place I bumped into them was when I was returning JSON from a server:

response.contentType = "application/json"

There's another one - application/json.

So they're not completely alien to us - they're a way of saying that "the file is full of CSS", and "I'm sending you some JSON". Let's use these two types as examples when we look at the syntax.

Media Type Syntax

A media type is made of two fields separated by a /. The first is the type and the second is the subtype.

Straight off we can see that CSS (text/css) has a type of text and a subtype of css. The text type is very broad - it says that the media is just text, which covers quite a few types of content - content such as:

text/html - it's what you're reading right now!
text/plain - it's just plain text!
text/markdown - what I'm writing this in which will get turned into text/html
text/csv ...

you get the idea.

application/json has a subtype of json, which is appropriate as, well, it is JSON. The application type informs us that this is a type that's meant to be processed by a application. This kinda makes sense, as it's JSON, which is meant to be read by computers.

(But isn't CSS only meant to be processed by an application? Yes, it is. Maybe it should have been application/css. Maybe it should have been text/json. Who knows. Media types are a bit wonky. The whole web is a bit wonky. Don't worry about it too much. Part of being a web developer is learning to live with a fair amount of kludge and ambiguity that happened before some of us were born. Learn to live with it.)

Other fun application types are

application/pdf for PDFs
application/zip for zip files
and many, many more...

All the types

We've seen text and application types - here's a list of types that you're likely to come across with examples:

type	purpose	example
`application`	media for application consumption	`application/json`
`audio`	audio media	`audio/mp3`
`font`	font formats	`font/ttf`
`image`	visual media	`image/gif`
`multipart`	media that needs to be sent in parts	`multipart/form-data`
`text`	human readable text	`text/html`
`video`	video media	`video/mp4`

Type and subtype are the only parts of a media type that are required, but there are also couple of optional parts.

Parameters

Media types can have a list of parameters tagged on to them after a semicolon, made of key/value pairs separated by an =. For instance

text/plain;charset=UTF-8

is a text/plain media type that's using the UTF-8 character encoding. If we want our sweet emojis to work we need to remember to say we're using UTF-8, else the client will assume we're writing in ASCII like 1970s cavemen.

Parameter types aren't dictated by the media type specification,² and you can have as many of them as you like:

text/plain;charset=UTF-8,blog-post=true,author=gypsydave5

They gain their meaning through context; browsers, for instance, will look for and use a charset parameter when they read a media type over HTTP. More on browsers in a bit.

Structured Syntax Name Suffix

This one's a bit weird, but it's also cool, so bear with me. Take a look at this media type:

image/svg+xml

This is the type for SVG images - Scalable Vector Graphics. image is the type, svg is the subtype - that's what we'd expect.

But what's this +xml doing at the end? Well, as you may already know, SVGs are written in XML - it's one of the nicest things about them. So the +xml is telling us that the syntax of SVG is XML; you could say that XML is the 'base' language for SVG. This is called the 'structured syntax name', and it's a nice way of letting us know that, hey, you may not know what SVGs are but, it's OK, it's just XML under the hood so you'll be fine.

(Unless you're me and you panic everytime you hear the word XML and you find it ridiculous that some people think it's human readable and you wish that the whole world was represented as JSON, but that's another story...)

Look, I can tell you're really excited by all these media types. Now you know how to understand them, you can read the list of all the media types that have been registered with IANA, the Internet Assigned Numbers Authority. Go on, read them all now. I'll wait.

There's a lot, right? Try not to panic - you'll probably only ever use ten of them at most. But did you see the one for SNES ROMs?

Media Types in HTTP Message Headers

The most important place you'll use media types is in HTTP messages. You'll use them to describe the media type of the data you want in the Accept header of an HTTP Request, and the type of data you're sending in the Content-Type header of an HTTP Response.

The `Accept` Header

The Accept header is the way a client - like your browser - can tell a server what sort of content it wants.

At its simplest it can look like this:

Accept: application/json

If I put this in the header of my request, I'd be making it very clear to the server that I want JSON back. No questions asked.³

But say you wanted some audio back from the server, but didn't mind what subtype - audio/mp3 is just as good as audio/wav for you. In this case you can say:

Accept: audio/*

* represents a wildcard - it means 'give me anything'. The server could legitimately reply with an audio media type with any subtype.

Finally, if you just don't care what comes back from the server you can just say

Accept: */*

The `Content-Type` Header

Content-Type is the header you should add to an HTTP Response message to tell the client what they're getting in the response body. This is how the client knows how to interpret the message that you're sending.

The Content-Type header should have one media type, so it could be as simple as this:

Content-Type: text/html

Which is hopefully the content type of the page you're reading now.

Wait, can't I just use a file extension?

You can imagine that you've got some data that you can get to through a URL:

http://gypsydave5/data

Maybe if I wanted to get the data as JSON I could request:

http://gypsydave5/data.json

But if I want XML instead I could do:

http://gypsydave5/data.xml

The benefit being that this is pretty easy to understand if I'm used to using a filesystem - I can just identify the type of file by the extension, and so I can now do the same with a URL.

What's the harm? Probably the most annoying thing is that, even if you provide an extension as above, you'll still have to provide a Content-Type header. This is because, on the web, information about content isn't meant to be encoded in URLs; it's meant to be in the Content-Type header.

Some popular frameworks do this,⁴ but it's a bad idea. Don't do it.

The biggest problem is that you'll miss out on being able to perform content negotiation.

Content Negotiation

Pretend you're going to a sandwich shop and your friend asks you to get a sandwich. Sure, you say, what do you want? I don't know, they say, what do they have? Um... you say, I really don't know - here's the menu but they've often run out of some of the fillings by this time of day.

OK, says your friend, here's what I'd like:

"I want tuna mayo or a New Yorker - either is fine. If they don't have those, then I'll take an egg salad. And if they don't have an egg salad, then please, get me anything - I'm starving."

Doesn't sound too bad. You can use your friend's set of sandwich requirements when you get to the sandwich shop to get them a sandwich that they'll like.

The same thing happens every day on the web, with clients sending a list of media types over to servers to try and make sure that they'll get something they like. Take a look at this Accept header of an HTTP Request sent from a web browser:⁵

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

The browser wants one of the above media types. But it's got some opinions about which ones it would prefer, which it's expressing using q parameters.⁶ q parameters have a value between 1 and 0, and the default value of a q parameter (when it's not supplied) is 1.

Here's the media types above written out with their q values.

media type	q value
`text/html`	1.0
`application/xhtml+xml`	1.0
`application/xml`	0.9
`/`	0.8

A series of choices ranked by preference. If you or I were going to the server to get the browser some content, the browser would tell us something like:

"I really want text/html and application/xhtml+xml. But, if they don't have those, I'd go for some sweet application/xml. And if they don't have that then, whatever, just get me anything."

Which is really what you'd want a browser to do - you always want to get something back.

Accept: audio/*

Is like we're being sent to the record store:

"Could you get me the new Nirvana album?⁷ I don't care if it's on vinyl, tape or CD. Hell, 8 Track will do. Just make sure I can listen to it, OK - I don't just want the poster."

This is content negotiation - our request to the server has given it our preferences regarding the content type we get back. It can go through those prefences, looking at what content types it can return, and give us the type that matches the most closely.

Content Negotiation and Testing

It's easier to write tests on the data that builds an HTML page than the HTML itself. If you build your application allowing the client to choose the type of content that comes back over each URL, you can test the contents of a 'page' by requesting the JSON representation rather than the HTML representation. Much easier!

Roll your own media type

Yes, you too can invent your own media types, and it's not as rare or as weird as you might think. In fact it's a powerful technique when writing web APIs. The media type specification has space for subtypes that aren't registered (and should never be registered). They start with x-:⁸

application/x-myapplication-orderstatus+json

This could be the media type for the order status in my application. +json lets everyone know that it's written in JSON, but we've tightly specified that the content is a part of myapplication - it's not just any old JSON.

This is just vanity if you don't choose to leverage it to pass on additional information about the media type. For instance, if you want to change the structure of the application/x-myapplication-orderstatus+json media type, you can add a version parameter:⁹

application/x-myapplication-orderstatus+json;v=1.1

This is very useful when describing the content types that are sent and received across an evolving REST API.¹⁰

Finally you can register your media type with IANA to let the world know how to interact with your application.

Summary

We've learned:

The syntax of a media type and what they mean.
How to use a media type in Content-Type headers to declare what we're sending.
How to use them in Accept headers to control the content type we get back.
How to use them to perform content negotiation with a server.

Media types are important - they help smooth the path of passing data around on the web. Using them - and using them well - will help make your web applications easier for you others to use and understand.

Q and A

Q: "Wait, I didn't put a Content-Type header on the HTML I sent but my browser still knew it was HTML - what gives?"

A: There are ways of working out the media type of data; go read up on content sniffing.

Q: Wait, don't you mean MIME types?

No, I don't. MIME means Multipurpose Internet Mail Extensions and was the first place that media types were used. But since they're not used solely for 'internet mail' (email to you and me), the proper name is 'media type'. People still tend to use MIME, media and content type interchangeably, but now you know the right answer you can look smug at parties and demand a pay rise.

This is HTML4 - you don't need to include the type in HTML5. But that would ruin this perfectly good example. ↩
Apart from q, this one is specified. ↩
In fact the server should send back a 406: Not Acceptable code if it can't supply the media type asked for... but this rarely happens. ↩
Active Resource in Rails ↩
In this case Firefox. ↩
The q stands for quality. I'm not even joking. ↩
I am very much down with popular culture. ↩
or x.. In fact x. is preferred by IANA but x- is more widely used. ↩
You could also try application/x-myapplication-orderstatus_1.0+json - it depends on how you want to parse the version information and what your versioning policy is (how compatible the versions are). ↩
Todays cover image by Julius Schnorr von Carolsfeld could easily have the header and custom media type Content-Type: text/x-commandments ↩

How I Write Blog Posts These Days

David Wickes — Tue, 02 Apr 2019 23:01:12 +0000

I read

How I Write Online Articles

John Papa for Microsoft Azure ・ Apr 1 '19

#devrel #vscode #markdown #discuss

and realised that I was doing things in a sufficiently different way to John to warrant a separate post. So, in some vague order, here's how I write a post for Dev.to and my own blog.

1. Editor: Vim

I write my Markdown in Vim. Or Emacs in Evil mode, which is just Vim emulation in Emacs.

Why? Well, I find the manipulation of text - any text - really quick and easy in Vim. Moving paragraphs, changing words, deleting sentences - Vim is aware of the structure of natural language, which makes using it to edit blog posts easy. But that's my experience which is coloured from having used it since the beginning of my career. You either like Vim or you don't - it's really not that important.

Why use Emacs and not just Vim? It just depends on whether I've got a terminal or Emacs open.

2. Format: Markdown

Markdown is both wonderful and terrible. Wonderful as it's everywhere, is human readable, is human writable, and supports the structures you want to use for technical writing - i.e. code blocks. Terrible because there is no standard - the HTML you'll get out of the other end of a parser is not consistent between parsers.

Think this isn't too much trouble? I have to join all the lines in a paragraph to a single line when I'm posting on Dev.to as the Markdown parser treats all the line breaks in a paragraph as hard breaks.¹

It's this inconsistency parsers that makes me avoid (or at least not rely on) Markdown linters and previewers. I tend to wait until the post is near finished before I see what it looks like with stage 5 (see below).

Still, the benefits outweigh the drawbacks and so Markdown it is.

3. Grammar and Spelling: aspell, style and diction

Markdown posts like this can be sent to aspell, a handy interactive and extensible spellchecker. Good editor integration for aspell exists in both Vim and Emacs.

style and diction are a pair of tools that check for grammar mistakes and readability. diction picks up on clichés, doubled-words and potential misspellings. It's sometimes wrong but it gets you thinking about whether you could word things better and so makes an excellent starting point.

style describes how readable your document is through a series of scores - Flesch-Kinkaid for instance. It's interesting information.

4. Storage: Public GitHub

I keep my posts on GitHub. If someone spots a mistake then at least this way they can open a pull request.

5. My Site: Static Site + GitHub Pages

I've been using GitHub Pages to host my blog as a static site since forever. It's an easy enough hosting solution and you can use it with any number of static site generators to turn your Markdown into HTML.

I wrote my own static site generator because I found every one I tried a little too busy for my liking. It's still too busy for my liking and I reckon it could be scrapped in favour of Pandoc and a few Bash scripts as glue, but it was fun to write. I wouldn't use it if I were you.

There's also some MathJax in there for the posts I wrote about Lambda calculus which is overkill as I'm not a mathematician and it just adds a load of JavaScript to the page. But it's pretty so 🤷‍♀️.

I have a horrible bash script to publish the blog, and it looks like this when it's published:

I like the colour orange.

6. Add to Dev.to: Copy and Paste

Hey, it works.²

7. Dev.to Cover Picture: Moses

My personal site has no place for cover images, but Dev.to does and so I feel obliged to put something there.

What I write can come across as an angry old man coming down from a mountain to shout at everyone to stop worshipping false idols,³ so a picture of Moses always makes an approprite Dev.to cover image. Usually something involving smashing tablets and looking angry, but this time I've been a bit more peaceful and so it's The Finding of Moses by Lawrence Alma-Tadema.

Would be annoying if it wasn't for Vim's vip J. ↩
Also made more exciting by Vim: :% y + ↩
At least that's what the score from style says. ↩