Communication as a programmer

Communication is important

Question for you; is the header title immediately above this sentence good or bad? Or perhaps more accurately, where does it sit on a communication scale of bad to good?

Some people might read it and say I've concisely summarised the point I (hope I) am making in the forward text. Others might interpret it as vague, wishy-washy and not really telling them much if anything about what's on my mind, because "communication is important" is something of a platitudinous truism.

Kind of depends on your perspective, doesn't it? And of course it does; I loaded the question, notions of "good" and "bad" are inherently subjective judgements (not to start a philosophical debate on that one).

So perhaps a better question would be "Is my header title effective in achieving its purpose?" - we can maybe define some metric around that and get something useful out of it. If one of my goals is search engine optimization for keywords around communication skills, for example, I've unequivocally done a piss-poor job. If what I wanted was for a reader to take away that this section of my post is about establishing a theme and introduction to my way of thinking about the topic of communication, not just that it is important, but questions of why and how around that, it's....I'd say still not great, but does a slightly better job.

We (presumably) all agree communication is important, but as programmers we have a stereotypical reputation for being bad at it. My own inclinations and experiences tell me, like many stereotypes, this one has something resembling a grain of truth in there somewhere, it's just that grain is smothered in many layers like the heart of a pearl made from smooth, smokey whisps of lies and truths blended together.

Yet with what we do for a living, academia or hobby, communication too is at the heart (or centre of the pearl, or something) of what we do as programmers. We probably communicate with more audiences at more levels than the average employee in media.

What I'm going to explore in this post is where, in my experience, I have failed at effective communication, other programmers frequently fail at it and how we can do better by being more mindful of ourselves and the people we interact with. Communication is a skill, but more than that, it is one which is learned. Like all learned skills, it can erode if not exercised and kept in shape and it can become the victim of our own ego - or to put that another way, we can think we're better at it than we are.

The real reason I left the heading title above as a probably-not-so-good example of one is because I want you to stop and think for a minute about how you communicate and whether you use it effectively as a programmer. You could say the intention is for it to be a somewhat ironic heading. Oooooh, meta. I'll leave it to you to decide whether to that end, I've done a better job achieving my purpose.

Do programmers suck at communicating?

Good communication as a programmer is hard. Not because of who we are, but because we start at a disadvantage; we are expected to communicate in multiple languages to people who understand and interpret those languages completely differently and in ways we can't predict.

We have to communicate with other programmers, through code and how we design, label and structure that code. We have to communicate with other engineers or architects who may not speak code, but can speak the concepts fluently if they're expressed in the language of diagrams, or high level abstractions, or logistical exchanges.

We have to communicate with business people, who want our understandings translated to the lexicon of risk, complexity, time, cost, benefit, etcetera.

We have to communicate with customers, who may walk in to their kitchen and think we're a bit weird when we ask them if they've checked their cookies.

And we have to communicate with each other as programmers again, in the language of all of the above, because there are a hundred-plus popular programming languages, dozens of design patterns, a plethora of pitfalls and paradigms, innumerable network protocols and more opinions on the right way of doing things in any of those than there are people to do them.

Is it really surprising that sometimes, yes, we do suck at doing those things?

So where are we going wrong, and how can we fix it? The comprehensive answer to that, realistically, isn't going to be compressed in to the length of a Dave Gebler blog post (and those can be pretty darned verbose). But I will explore below a few of my thoughts and feelings about this, based only on my experience and introspection.

Ego-driven development

If I had a penny for every time I've interacted with another developer who's spoken to me in a smug, patronising manner which smacks of a belief that because I disagree with them about something, I must be ignorant, for if only I wasn't I would surely hold the same opinions they do....well, I wouldn't be rich, but I'd be at least the cost of a nutty, chewey Snickers better off.

And I'd love to tell you I've never done this, I'm not like that, I'm humble and respect other people's opinions. Oops, too bad for me I'm human, I guess. I could tell you that, but I don't need to be a betting man to be sure you can find people who know me and would raise a finger in the air to say "Ummm....that's not entirely true though, is it Dave?"

Look, we all think our opinions are the right ones (at the time we are expressing them). We must do, because if we didn't they wouldn't be our opinions. But if your first inclination on disagreement is to believe the other party is ignorant, I urge you to at least step back for a minute and ask yourself if it could be you who's the problem here. Are you being a practitioner of ego-driven development?

What I mean by this in respect of programmers is that as we put a lot of work in to building something, or advocating for a certain way of doing something, it can start off innocently enough with best intentions based on good knowledge and genuine proficiency. But because we put a lot of work (i.e. labour, energy, sweat) in to our way of doing whatever it is, over time our view creeps, without us noticing, to an emotional investment in how we're doing it. The scope creeps from "let's do it my way" to "it's my way or the highway, because I'm right, you ignorant jackass."

That's not cool. That's ego-driven development and it's a massive anti-pattern in collaborative software development.

I'm not saying there aren't people who through experience are more knowledgeable about some particular niche of comp-sci than others, or aren't able to make a qualitatively better justification or argument for doing something (or avoiding something). I'm saying it matters how we present that to people. Make your case, include all the relevant detail, listen to the feedback - if you still think someone genuinely doesn't possess some information which would help them understand your reasoning, give it to them. But don't try to make them feel small, or act like they should have known whatever you think you know, or that they are a worse programmer for not knowing something. The only things this will achieve is to a) put people off learning and b) make them think you're an egotistic twat.

P is for peer review

...not problem. When I peer review in my job, what I try to do is be mindful that I haven't written this code, I wasn't in the head of the person / people who wrote it and they may have a perspective on the problem space I don't. So I will broadly shy away from comments expressing an attitude like "you're missing this thing, you need to do it", or "this is not a good design pattern, do this instead". I find it's better and ultimately more productive (for both reviewer and reviewee) to ask questions - it's better to start with an assumption I am the one not understanding something. That way, only one of two things can happen. Either that was correct and I avoid wasting time picking bones over legitimate contributions, or by explaining something to me, the other person begins to question themselves and comes around to realise I raised a valid point.

"I think we could probably factor out this block in to a couple separate methods and unit test them independently. Is there a reason we've decided to couple these bits together?"

"It looks to me like this method isn't meant to be used directly? I'm concerned it being public could encourage a consumer to access this bit of state in a way which could cause them to introduce errors. Perhaps it's worth adding a comment to explain why it's necessary? Or if not, suggest we make it private."

These are contrived examples, of course, but you get the principle - ask questions, don't assume, don't be too quick to accuse someone of introducing a problem when they may have a good reason you didn't know about. Absolutely do trust your knowledge, your skills and your instincts; raise your concerns and ask for explanations.

Also I recommend using "we" rather than "you" - it's peer review, we're part of a team. Take collective responsibility for the quality of your code.

F is for feedback

...not fuck you. On the converse end of the section above, don't be defensive about your code when other programmers (who let's assume, just for a moment, are equally as practiced and skilled as you are) have questions about it. Something may have seemed (and still seem) like the bonafide best practice, best solution, best way of doing it when you wrote it. Doesn't mean there isn't an array of improvements which could be made. Hell, it doesn't mean you haven't made a horrendous error in judgement. That happens to the best of us. Honestly, I'm disappointed in myself if at least once every 12 months, I can't look back on something I wrote in that time and laugh about it; "Haha, that's ridiculous, why did I think that was remotely a good idea at the time?" - the only thing that means is I've grown and learned new things.

I kid you not, I once started working on a small portion of a codebase for a task and was confronted by a mess. Like, I spent an hour just picking through it in grumpy and derisive awe, saying to myself who is the fucking idiot who put this together? Yeah, turns out it was me, about 18 months earlier.

When other programmers share knowledge, or even perspective, they are trying to help you. They are helping you, whether future, more grown up you comes to agree with their perspective or not.

There are many times I've gritted my teeth when someone's asked me to make a change, seeing nothing wrong myself with my own work (like duh, Dave, that's why it's peer review) and thought "fuck you."

This is totally wrong, and writing defensive comments in response to peer review feedback, challenging who dare force your ego to suffer the indignity of being questioned, "I don't agree with your comment. This method adequately solves the problem and you haven't proved there is a bug. I see no reason to change the branch and delay the ticket", this kind of crap is also totally wrong. I've done it, you've done it, don't do it.

I'm not going to go in to process for resolving irreconcilable differences of opinion in peer review, because I've been writing this post for about an hour and a half already. But there are communication techniques to help us do that too.

A is for audience

...not asshole. In the spirit of questioning ourselves, whenever you write or prepare something (especially for a non-programmer audience), be it an email, presentation, reply to a customer support ticket, whatever - try to put yourself in the shoes of that audience before you finalise it. If I were a business analyst, or a tester, or a customer and I didn't know the things I know, would I understand this?

Customers might not know much about what cookies are, but they know how to look at their screen and click on things if you walk them through it and they'll get the concept of cookies if you break it down in to crumbs for them.

Testers might not know how to check what branch of code is running somewhere, or what the public key of a certificate means, but they know how to check if a series of inputs and outputs are what they should be - and they considered inputs and outputs you didn't, precisely because you knew how those inputs were processed in minute detail. So talk in their language; given this, when that, this should happen.

If you find yourself thinking someone is a bit frustrating to explain something to smoothly, the likelihood is the source of your frustration is that you are failing to articulate something in a manner which is suitable for your target audience. Last time you went and saw a movie you hated, did you blame yourself for not understanding the movie, or did you blame the movie-makers for telling a story badly and not understanding their audience? If you are the source of some information which needs to be communicated, it is your job to do that in an appropriate way, it's not the job of your audience to guess what you meant or know what you know.

To err is human, to exit 1 is programmer

The take-away for me in all of this, knowing I am sometimes guilty of everything I've just said we shouldn't do, knowing everyone I've ever worked with is likewise so, is to recognise we are all human. We all have our own perspective, our own ideals, we make mistakes, we have moods and swings and roundabouts and good days and bad days.

We need to be a little more forgiving of both ourselves and our neighbours.

People aren't code; they don't behave in consistent, predictable ways or produce exactly the same results given exactly the same set of circumstances. If there is any truth to the stereotype about programmers being bad communicators, I think it might be in us sometimes forgetting that.

---

Comments