A colleague asked me recently:

Why aren’t developers writing comments any more?

He’d been looking through some code his team had written, and couldn’t understand it – he was looking for comments to make sense of the mess, but there were none. Before he challenged the team, he asked my opinion: should developers be writing comments?

Excessive Comments

When I started programming some years ago, I would comment everything, and I mean everything.

    // Add four to x
    x += 4;

My logic at the time was that it was impossible to tell the difference between uncommented clear code and gnarly code you just hadn’t spotted the gnarliness in yet. So I would comment everything, where the absence of a comment meant I’d forgotten – not that it was so trivial as to not warrant mentioning.

No Comments

Eventually I started working with peers who knocked some sense into me, and I immediately halved the number of lines of code I produced. At first it was a shock, but soon I realised that clear code is easier to read if there’s just less noise. And this is all (most) comments become: noise. Sometimes they’re accurate, sometimes they’re not. But you can’t rely on them, you always have to assume they might be wrong. So if the code and the comment seem at odds, you assume it’s the comment that’s wrong and not your understanding of the code (naturally you’re infallible!)

Clean Code

Uncle Bob and the notion of clean code have taken “no comments” to an almost fanatical zeal. But every time I get into an argument with someone about how maybe this time a comment might be justified: Ctrl-Alt-M, enter your comment as the method name and it makes the code more obvious. Every. Damned. Time.

However, the trouble with a zealous argument like this is it gets taken up by asshats and lazy people. It’s too easy to say “if you’d read Clean Coder you’d know you don’t need comments. Quit living in the past, grandpa!”. Uh huh. But your code is still a muddled pile of indecipherable crap. At least with comments there’d be some signposts while I wade through your steaming mess.

Some Comments

The truth is: sometimes comments do help (squeal clean code weenies, squeal!) There are some cases where extracting a method name isn’t sufficient. Sometimes having 20 one line methods in my class does not make it easier to read. The end goal is to produce understandable code. Generally, naming things properly helps. Adding comments that get stale does not. But that doesn’t mean that writing crap code and not commenting is the answer. Don’t use “no comments” as an excuse to leave your code indecipherable by human beings.

For example, sometimes you need to document why you didn’t do something. Maybe there’s a standard way of converting between currencies in your application – which this one time you’ve deliberately not used. A comment here might help future people not refactor away your deliberate choice (even better is baking your decision into a design – some class structure that makes it really obvious). Sometimes a method name really doesn’t do a line of code justice, it’s better to be seen in the context of the lines before and after it – but it really needs some explanation of what you’re doing. This is particularly true when dealing with complex algorithms or mathematical formulae.

Getting the Balance Right

How do you get the balance right? Well, your goal is to make code that other people can understand. The best way to get feedback on that is to ask someone. Either have explicit code reviews or pair program. If another human being has read your code and they could understand it – there’s a better than average chance that most other capable people will be able to read it too.

Newcomers to TDD ask some interesting questions, here’s one I was asked recently: testing private methods is bad, but why?

How did we get here?

If you’re trying to test private methods, you’re doing something wrong. You can’t get to TDD nirvana from here, you’re gonna have to go back.

It all started with an innocuous little class with an innocuous little method. It did one little job, had a nice little unit test to verify it did its thing correctly. All was right with the world. Then, I had to add an extra little piece of logic. I wrote a test for it, changed the class until the test passed. Happy place. Then I started refactoring. I realised my little method, with its handful of test cases was getting quite complicated, so I used the extract method refactoring and boom! I have a private method.

While simple when I extracted it, another couple of corner cases and this private method evolves into quite a complicated piece of code – which now I’m testing one level removed: I’m testing the overall functionality of my outer method, which indirectly tests the behaviour of the private method. At some point I’m going to hit a corner case that’s quite awkward to test from the outside, it’d be so much easier if I could just test the private method directly.

What not to do

Don’t use a test framework that let’s you test private methods. Good God, no. For the love of all that is right with the world step away from the keyboard.

What to do instead

This is a prime example of your tests speaking to you. They’re basically shouting at you. But what are they saying?

Your design stinks!

If you need to test a private method – what you’re doing wrong is design. Almost certainly, what you’ve identified in your private method is a whole new responsibility. If you think about it carefully, it probably isn’t anything to do with what your original class is. Although your original class might need renaming to make that obvious. That’s ok, too. That’s incremental design at work.

An example would help about now

Say I started off with a Portfolio class – it has a bunch of Assets in it, each of which has a Value. So I can implement a Portfolio.GetValue() to tell me how much it’s all worth. But then I start dealing with weird corner cases like opening or closing prices. And what do I mean by value, what I could sell it for, right now? Or perhaps there’s some foreign currency conversion to do, or penalty clauses for early exit, how does all that get factored in?

Before too long, GetValue() has a fairly large piece of logic, which I extract into GetSpotSalePrice(Asset). This method is then hairy enough to need testing, so it’s pretty clear that my design stinks. The deafening din of my tests, finally persuades me to extract GetSpotSalePrice(Asset) into another class, but here’s the million dollar question: which?

What not to do – part 2

For the love of SOLID, don’t put it in a AssetSalePriceCalculator, or a SalePriceManager. This is the number one easy mistake to make – you can follow TDD and ignore decent OO design and still end up with a steaming turd pile of horribleness.

NounVerber class is always a design smell. Just stop doing it. Now. I mean it. I’m watching you. I will hunt you down and feed you to the ogre of AbstractSingletonProxyFactoryBean.

What should I do then?

The answer might seem obvious, but to too many people starting out doing TDD and half-decent design – it isn’t at all obvious. The method needs to move to a class where that responsibility makes sense. In our example, it’s crushingly obvious this is really a method on Asset – it even passes one in. If your method has one class parameter and uses a bunch of data from that class, you can bet your bottom dollar you’re suffering feature envy. Sort your life out, apply the method move refactoring. Go live happily ever after.


Why shouldn’t you test private methods? Because the fact you’re asking the question means the method shouldn’t be private – it’s a piece of independent behaviour that warrants testing. The hard choice, the design decision, is where you stick it.



What makes you a “senior developer”? Everyone and their dog calls themselves a senior developer these days. From fresh graduates to the CTO, everyone is a senior developer. But what the hell does it even mean?


Some developers are avid technologists. They got into programming really because they like tinkering. If it hadn’t been 7 languages in 7 weeks, it would have been a box of meccano or they’d be in their shed busy inventing the battery operated self-tieing tie. These people are great to have on your team, they’ll be the ones continually bombarding you with the latest and greatest shiny. If you ever want to know if there’s an off the shelf solution to your problem, they’ll know the options, have tried two of them, and currently have a modified version of a third running on their raspberry pi.

The trouble with technologists is more technology is always the answer. Why have a HTTP listener when you can have a full stack application server? Why use plain old TCP when you can introduce an asynchronous messaging backbone? Why bother trying to deliver software when there’s all these toys to play with!


Some developers naturally gravitate towards providing tools for the rest of the developers on the team. Not for them the humdrum world of building some boring commercial website, instead they’ll build a massively flexible website creation framework that through the magic of code generation will immediately fill source control with a gazillion lines of unmaintainable garbage. Of course, that’s assuming it works, or that they even finish it – which is never guaranteed.

There’s a certain kudos to being the tools guy on the team: you don’t want the most junior member of the team creating tools that everyone else uses. If he screws up, his screw up will be amplified by the size of the team. Instead one of the smart developers will see a problem and start sharpening his tools; the trouble is you can spend an awful long time creating really sharp shears and somehow never get round to shaving the yak.

Backend Boys (and Girls)

Another common pull for a lot of developers is to get further down the stack, away from those messy, annoying users and nearer to the data. Here you can make problems more pure, really express your true artistry as a developer and an architect. It’s true: as you move down the stack you tend to find the real architectural meat of a system, where you want the developers who can see the big picture of how everything interacts. The seasoned professionals that understand scalability, availability and job-security.

It’s pretty easy to put off outsiders (project managers, customers, sniveling little front end developers) – you start drawing diagrams with lots of boxes and talk of enterprise grade messaging middleware and HATEOAS service infrastructure, before you know it their eyes have glazed over and they’ve forgotten what they were going to ask you: like perhaps why this has taken six months to build instead of six days?


Some developers just Get Things Done. Sure their methods might be a little… slapdash. But when you’re in a crunch (when aren’t you?) and you need something done yesterday, these are the people you want on your team. They won’t waste time designing a big complex architecture; they won’t even waste time writing automated tests. They’ll just hammer out some code and boom! problem solved.

Sometimes they can come across as heroes: they love nothing better than wading into a tough battle to show how fast they can turn things around. Of course, that also lets them quickly move from battlefield to battlefield, leaving others to clean up the dead and wounded they’ve left behind.

Front End Developers

For some reason Front End developers never seem to be considered the most senior. As though hacking WPF or HTML/CSS was somehow less worthy. In fact, I think the front end is the most important part – it’s where all your wonderful n-tier architecture and multiple redundant geegaws finally meets users. And without users, everything else is just intellectual masturbation.

The front end developers are responsible for the user experience. If they make a mess, the product looks like crap, works like crap: it’s crap. But if the front end developers create a compelling, easy to use application – it’s the great, scalable architecture underneath that made it all possible. Obviously.

Team Lead

Your team lead probably isn’t a senior developer. Sorry, bro: if you’re not coding you can’t call yourself anything developer. Go easy on your team lead though: the poor sod probably wrote code once. He probably enjoyed it, too. Then some suit decided that because he was good at one job, he should stop doing that and instead spend his life in meetings, explaining to people in suits why the product he’s not writing code for is late.


Your architect probably isn’t a senior developer either. Unless he’s actually writing code. In which case, why does he need the label “architect”? Architecture is a team responsibility. Sure, the most senior guy on the team is likely to have loads of experience and opinions to share with the team – but it doesn’t mean his pronouncements should be followed like scripture. But if instead of writing code you spend your time drawing pretty pictures of your scalable messaging middleware one more time, I will shove it up your enterprise service bus.


There are lots of different types of senior developer. That’s probably why the term has got so devalued. Once you’ve been in the industry for a few years, you’ll have found yourself in at least one of these roles and can immediately call yourself senior. The truth is you spend your whole life learning, only in an industry this young and naive could someone with 3 years experience be called “senior”. I’ve been programming professionally for 13 years and I’m only just starting to think I’m getting my head around it. I’m sure next year I’ll realise I’m an idiot and there’s a whole new level to learn.

So, go ahead, call yourself senior developer. Just make sure you keep on learning. Change jobs, wear a different hat. Be the tools guy. Meet like-minded developers. Play with different technologies. Become a middle tier developer. Then switch to work on user experience.

Senior developer: it’s just a job title, after all.

Where I work we have an unusual split: although the developers use C#, we also work with engineers who use Matlab. This allows the engineers to work in a simple, mathematics friendly environment where working with volumes of data in matrices is normal. Whereas the developers work with real computer code in a proper language. We get to look after all the data lifting, creating a compelling user interface and all the requisite plumbing. Overall it creates a good split. Algorithms are better developed in a language that makes it easy to prototype and express complex algorithms; while dealing with databases, networks and users is best done in a proper object oriented language with support for a compile time checked type system.

As part of a recent project for the first time we had a lot of data flowing through Matlab. This led to us have to verify that our matlab code, and our integration with it from C#, was going to perform in a reasonable time. Once we had a basic working integrated system, we began performance testing. The initial results weren’t great: we were feeding the system with data at something approximating a realistic rate (call it 100 blocks/second). But the code wasn’t executing fast enough, we were falling behind at a rate of about 3 blocks/second. This was all getting buffered in memory, so it was manageable but creates a memory impact over time.

So we began scaling back the load: we tried putting 10 blocks/second through. But the strangest thing: now we were only averaging 9.5 blocks/second being processed. WTF? So we scaled back further, 1 block/second. Now we were only processing 0.9 blocks / second. What in the hell was going on?


Let’s plot time to process batches of each of the three sizes we tried (blue line), and a “typical” estimate based on linear scaling (orange line). I.e. normally you expect twice the data to take twice as long to process. But what we were seeing was nearly constant time processing. As we increased the amount of data, the time to process it didn’t seem to change?!

We checked and double checked. This was a hand-rolled performance test framework (always a bad idea, but due to some technical limitations it was a necessary compromise). We unpicked everything. It had to be a problem in our code. It had to be a problem in our measurements. There was no way this could be realistic – you can’t put 1% of the load through a piece of code and it perform at, basically, 1% of the speed. What were we missing?

Then the engineers spotted a performance tweak to optimise how memory is allocated in Matlab, which massively speeded things up. Suddenly it all started to become clear: what we were seeing was genuine, the more data we passed into Matlab, the faster it processed each item. The elapsed time to process one block of data was nearly the same as the elapsed time to process 100 blocks of data.

Partly this is because the cost of the transition into Matlab from C# isn’t cheap, these “fixed costs” don’t change depending whether you have a batch size of 1 or 100. We reckon that accounted for no more than 300ms of every 1 second of processing. But what about the rest? It seems that because of the way Matlab is designed to work on matrices of data: the elapsed time to process one matrix is roughly the same, regardless of size. No doubt this is due to Matlab’s ability to use multiple cores to process in parallel and other such jiggery pokery. But the conclusion, for me, was incredibly counter intuitive: the runtime performance of matlab code does not appreciably vary based on the size of the data set!

Then the really counter intuitive conclusion: if we can process 100 blocks of data in 500ms (twice as fast as we expect them to arrive), we could instead buffer and wait and process 1000 blocks of data in 550ms. To maximize our throughput, it actually makes sense to buffer more data so that each call processes more data. I’ve never worked with code where you could increase throughput by waiting.

Matlab: it’s weird stuff.

How do you choose the right language to use for your next project? Use the right tool for the job? Sure, but what does that mean? And how do I know what the right tool is? How do I get enough experience in a new language to know whether or not it is the right tool for the job?

Your choice of language will have several impacts on your project:

  • Finding & hiring new developers to join your team
  • Whether there is a thriving community: both for providing Q&A support and the maturity of libraries & frameworks to help you get more done
  • Training your existing team; discovering and learning new tools; as well as the possible motivation impact of using new technologies
  • Finally your choice of “the right tool for the job” will make the development effort easier or harder, both in the short-term and for long-term maintenance

This is the first article in a series on choosing the right language – we will start by addressing recruitment.


For many teams, recruiting new staff is the hardest problem they face. While choice of programming language has many obvious technical impacts on the development process, it also has a huge impact on your recruitment efforts. If your choice of language has the ability to make your hardest problem easier then it has to be considered.


The truth is that most developers will naturally filter themselves by language, first and foremost. Most Java developers, when looking for jobs, will probably start by asking their Java developer friends and searching job sites for Java developer jobs. Recruiters naturally further this – they need a simple, keyword friendly way to try and match candidates to jobs, and filtering by language is an easy way to start.

Of course, this is completely unnecessary – most developers, if the right opportunity arose, would happily switch language. Most companies, given the right candidate, would be more than happy to hire someone without the requisite language background.

Yet almost every time I’ve been involved in recruitment we’ve always filtered candidates by language. No matter how much we say “we just want the best candidates”, we don’t want to take a risk hiring someone that needs a couple of months to get up to speed with our language.

My last job switch involved a change of language, the first time in 10 years I’ve changed language. Sure, it took me a month to become even competent in C#; and arguably three or four months to become productive. But of course it is possible, and yet it doesn’t seem to be that common.

This is purely anecdotal: I’d love to find a way to try and measure how often developers switch languages – just how common is it for companies to take on developers with zero commercial experience in their primary language? How could we measure this? Could we gather statistics from lots of companies on their recruitment process? Email me or post a comment below with your ideas.

Size of Talent Pool

Ultimately your choice of language has one main impact on recruitment: which language would make it easiest to find good developers? I think we can break this down into three factors:

  1. Overall number of developers using that language
  2. Competition for these developers from other companies
  3. The density of “good” developers within that pool

Total Number of Developers

Some languages have many more developers using them than others. For example, there are many times more Java developers than there are Smalltalk developers. At a simple level, by looking for Java developers I will be looking for developers from a much larger pool than if I search for Smalltalk developers. But how we can we quantify this?

We can estimate the number of developers skilled in or actively using a particular language by approximating the size of the community around that language. Languages with large communities indicate more developers using and discussing them. But how can we measure the size of the community?

GitHub and StackOverflow are two large community sites – representing open source code created by the community and questions asked by the community. Interestingly they seem to have a strong correlation – languages with lots of questions asked on StackOverflow have lots of code published on GitHub. I’m certainly not the first to spot this, I found a good post from Drew & John from a couple of years back looking at the correlation: http://www.dataists.com/2010/12/ranking-the-popularity-of-programming-langauges/

GitHub & StackOverflow probably give a good indication of the size of the community around each language. This means if we look for C# developers, there are many times more developers to choose from than if we choose Ada. However, sheer numbers isn’t the full story…

Competition for Developers

We’re not hiring in a vacuum – there is competition for developers from all the other companies hiring in our area (and those remote companies that don’t believe geography should be a barrier). This competition will have two impacts: first if there is more competition for developers using a certain language, that makes it harder to attract them to our company. Assuming market forces work, it also suggests that average salaries for developers with experience in an in-demand language will naturally be higher – as companies use salary to differentiate themselves from the competition. Just because there are more C# developers than Ada developers, the ease with which you can hire developers from either group is partly dependent on the amount of competition.

so-questions-adsI looked at the total number of questions tagged on StackOverflow.com and the number of UK job ads requiring the language on JobServe.com. Interestingly there is a very strong correlation (0.9) – this suggests, perhaps not surprisingly, that most developers primarily use the language they use in their day job: there are large communities around languages that lots of companies hire for; and only small communities around languages that few companies hire for. Of course – it’s not clear which comes first, do companies adopt a language because it has a large community, or does a large community emerge because lots of developers are using it in their job?

There are some interesting outliers: there seems to be greater job demand than there is developer supply for some languages such as Perl and VisualBasic. Does this suggest these are languages that have fallen out of favour, that companies still have investment in and now find it hard to recruit for? Similarly Scala and Node.js seem to have more demand than developers can supply. On the other side of the line, languages such as PHP and Ruby have much more active communities than there is job demand – suggesting they are more hobbyist languages, languages amateurs and professionals alike use in their spare-time. Then there is Haskell, another language with a lot of questions and not many jobs – perhaps this is purely its prevalence in academia that hasn’t (yet) translated to commercial success?

In general the more popular languages have more competition for developers. Perl & VisualBasic will be harder to find developers skilled in; whereas PHP, Ruby & Haskell should be easier to find developers. Besides these outliers, whichever language you hire for the overall size of the pool of developers (i.e. those within commuting distance or willing to relocate) is the only deciding factor. How many companies continue to use the mainstream languages (Java and C#) because its “easier” to hire developers? On the basis of this evidence, I don’t think its true. In fact, quite the opposite: to get the least competition for developers (lower salaries and less time spent interviewing) you should hire developers with Ruby or Haskell experience.

Density of Good Developers

One of the more contentious ideas is that filtering developers by language allows you to quickly filter out less capable developers. For example, by only looking at Python developers, maybe on average they are “better” than C# developers. My doubt with this is if it were found to be true, developers would quickly learn that language so as to increase their chances of getting a job: quickly eliminating any benefit of using language as a filter. It also starts to sound a bit “my language is better than your language”.

But it would be interesting if it were true, if we could use language as a quick filter to get higher quality candidates; it would be quite possible to gather data on this. For example, I use an online interview that could easily be used to provide an A/B test of developers self-selecting based on language. Given the same, standardized recruitment test – do developers using language A do better or worse than those using language B? Of course, the correlation between a recruitment test and on the job performance is very much debatable – but it could give us a good indication of whether there is correlation between language and (some measure of) technical ability. Would this work, is there a better way to measure it? Email me or post a comment below.


Popular languages have more developers to hire from but more companies trying to hire them. These two factors seem to cancel each other out – the ratio of developers:jobs is pretty much constant. As far as recruitment is concerned then, maybe for your next project break away from the norm and use a non-mainstream language? Is it time to hire you some Haskell?

Software is taking over the world. Arguably software has already taken over the world. The trouble is: software is all shit – and it’s all your fault.

I had one of those seconds-from-flinging-something-heavy-through-my-tv days yesterday: I really have had it with crappy software. First, I decided to relax and catch up with last week’s Have I Got News For You on BBC iPlayer. Unfortunately, for some unfathomable reason, the XBox iPlayer app has become shit in recent months. Last night, it played 0.5 seconds of the show and hung. Network traffic was still flying by, but none of it was appearing on my TV. Fine, I switched to using iPlayer on my laptop – at least that normally works.

Afterwards I decided to watch another of the (excellent, by the way) American remake of House of Cards on Netflix. First, my router had got its knickers in a twist and switched the VPN so Netflix thought I was in the US, so all of my recently watched had disappeared. Boot up laptop (again), login to admin page on the router, fiddle with settings, reboot, reboot XBox, login again: there we go, UK Netflix is back, I can finally watch House of Cards. Except now the TV has crashed and refuses to decode the HDCP signal from the XBox. Reboot TV: no. Reboot xbox, again. Yes! We have signal!

I sat back and started watching. I have to get up, three times, because the volume is quieter than a quiet thing on quiet day in quiet land. Eventually it was so damned quiet I manage to miss some dialog, so I get to use the, occasionally awesome, XBox kinect voice control feature that saves me scrabbling to find the controller: “xbox rewind”. Excellent, it starts rewinding. “xbox stop”. “XBOX, STOP!” “Oh for fuck’s fucking sake xbox, fucking stop you fucking retarded demon, STOP!”. Find the controller. Wait for it to boot up. Now the Netflix app has resumed its entirely random bug where I lose all the on screen navigation controls, so I have to guess which combination of up, down, A, A, B, up, down stops the bloody rewind and not the one that invokes the super Netflix boss level. Eventually the button mashing exits Netflix, not what I intended but at least it’s stopped rewinding. I launch Netflix again. This time the on screen controls work. Woohoo! Now volume has switched back to slightly louder than a jet engine piped directly against your ear drum, so I jump up and turn the volume down before it wakes my little boy up.

By now, I’m in no mood for political intrigue – killing every developer that was involved in any of the pieces of software that have ruined my mood and my evening, quite gladly: pass me the knife, I’m happy to relieve each them of their useless lives and hopelessly misapplied careers.

The trouble is: it’s not their fault. All software is shit. As software takes over more and more of my life I realise: it’s not getting any better. My phone crashes, my TV crashes, my hi-fi crashes. My sat nav gets lost and my car needs a BIOS upgrade. This is all before I get to work and get to use any actual computers. Actual computers that I actually hate.

Every step of every day, software is pissing me off. And you know what? It’s only going to get worse. As software invades more and more of our lives our complete inability to create decent, stable software is becoming a plague. The future will be dominated by people swearing at every little computer they come into contact with. In our bright software future where everything is digital and we’re constantly plugged into the metaverse I will spend my entire life swearing at it for being so unutterably, unnecessarily shit.

You know what else? As software developers: it’s all our fault.

Visualizing Code

When writing software we’re working at two levels:

  1. Creating an executable specification of exactly what we want the machine to do
  2. Creating a living document that describes the intent of what we want the machine to do, to be read by humans

The first part is the easy part, the second part takes a lifetime to master. I read a really great post today pointing out signs that you’re a bad programmer. Whether you’re a bad programmer or just inexperienced, I think the biggest barrier is being able to quickly and accurately visualize code. You need to visualize what the application actually does, what happens at runtime; but all your IDE shows you is the raw, static, source code. From this static view of the world you have to infer the runtime behaviour, you have to infer the actual shape of the application and the patterns of interaction; while closely related, the two are separate. Given just source code, you need to be able to visualize what code does.

What does it mean to visualize code? At the simplest level, it’s understanding what individual statements do.

string a = "Hello":
string b = "world";
a = b;

It might sound trivial, but the first necessary step is being able to quickly parse code and mentally step through what will happen. First for basic statements, then for code that iterates:

while (stack.Count() > 1)
    var operation = stack.Pop() as IOperation;
    var result = operation.Execute(stack.Pop(), stack.Pop());

Where you need to understand looping mechanics and mentally model what happens overall not just each iteration. Then you need to be able to parse recursive code:

int Depth(ITreeNode node)
    if (node == null)
        return 0;
    return 1 + Math.Max(Depth(node.Left), Depth(node.Right));

Which is generally harder for inexperienced programmers to understand and reason about; even though once you’ve learned the pattern it can be clearer and more concise.

Once you’ve mastered how to understand what a single method does, you have to understand how methods become composed together. In the OO world, this means understanding classes and interfaces; it means understanding design patterns; you need to understand how code is grouped together into cohesive, loosely coupled units with clear responsibilities.

For example, the visitor pattern has a certain mental structure – it’s about implementing something akin to a virtual method outside of the class hierarchy; in my mind it factors a set of classes into a set of methods.

public interface IAnimal
    void Accept(IAnimalVisitor visitor);

public class Dog : IAnimal { ... }
public class Cat : IAnimal { ... }
public class Fox : IAnimal { ... }

public interface IAnimalVisitor
    void VisitDog(Dog dog);
    void VisitCat(Cat cat);
    void VisitFox(Fox fox);

The first step in reading code is being able to read something like a visitor pattern (assuming you’d never heard of it before) and understand what it does and develop a mental model of what that shape looks like. Then, you can use the term “visitor” in your code and in discussions with colleagues. This shared language is critical when talking about code: it’s not practical to design a system by looking at individual lines of code, we need to be able to draw boxes on a whiteboard and discuss shapes and patterns. This shared mental model is a key part of team design work; we need a shared language that maps to a shared mental model, both of the existing system and of changes we’d like to make.

In large systems this is where a common language is important: if the implementation uses the same terms the domain uses, it becomes simpler to understand how the parts of the system interact. By giving things proper names, the interactions between classes become logical analogues of real-world things – we don’t need to use technical words or made up words that subsequent readers will need to work to understand or learn, someone familiar with the domain will know what the expected interactions are. This makes it easier to build a mental model of the system.

For example, in an online book store, I might have concepts (classes) such as book, customer, shopping basket, postal address. These are all logical real world things with obvious interactions. If I instead named them PurchasableItem, RegisteredUser, OrderItemList and DeliveryIndicationStringList you’d probably struggle to understand how one related to the other. Naming things is hard, but incredibly important – poor naming will make it that much harder to develop a good mental model of how your system works.

Reading code, the necessary precursor to writing code, is all about building a mental model. We’re trying to visualize something that doesn’t exist, by reading lines of text.

%d bloggers like this: