15 Feb 2018

feedPlanet Twisted

Itamar Turner-Trauring: I took a sick day today, and that's OK

I skipped work today because I'm sick: nothing terrible, nothing life threatening, I'm just-exhausted. I definitely can't focus on code, I can't even focus on television; so far I've been re-reading a favorite old novel, and looking at Twitter when I get distracted.

The world will not come to an end because I'm not working. My company won't collapse because I took the day off. My project will not fail.

I'm sick and I'm taking the day off, and that's OK. And if you can't take a day off-whether because you're sick, or just because you feel like it-then something is very very wrong.

And now… I think I'm going to lie down on the sofa.

15 Feb 2018 5:00am GMT

11 Feb 2018

feedPlanet Twisted

Itamar Turner-Trauring: The futile comfort of working long hours

Working long hours as a programmer can be both comforting and comfortable. After all, you have an easy solution to every problem: a few more hours at your desk, a few more hours staring at a screen in the dark. And working long hours is a natural attitude to take, since at the root of it, working long hours comes from valuing work, your craft as a programmer, and your obligations as a professional.

There is a different approach you can take. Instead of valuing work, you can value outcomes: outcomes at your job, outcomes in your life, outcomes in the world. Valuing outcomes is not comfortable. It forces you to reconsider and doubt your every step, and if you fail-and we all fail occasionally-your hard work becomes worthless.

But while valuing outcomes is uncomfortable and difficult, if you do it long enough you will find yourself-every once in the while-with the ability to grasp the moment and change the world. Just a little, in whatever corner you live in, but change it nonetheless.

The most direct way to learn this attitude is to reduce your working hours. If you had to do your work in 32 hours a week, instead of 45, or 50, or 60-what would need to change?

The experience of working fewer hours

Testing and quality

If you work long hours, you can pick some level of quality and stick to it:

But if you work fewer hours, you will need to make decisions and tradeoffs, because you won't have those extra hours. Some code will need automated tests for stability and maintainability, some code will need manual tests every time you change it, some code will be used once and thrown away. And you will need to make that choice, every single time. Which is to say, you will be forced to think about why you're writing this code, and what it will be used for.


If you work long hours, the direction you go in matters less: if it's the wrong direction, you can just work a few more hours when you eventually find out after you finish your task.

But if you work fewer hours, you will find yourself constantly plagued by doubt: is this the right direction? Are you doing the right thing? You may end up changing direction half-way, abandoning your work-however much it pains you-when you realize there's a better way to your destination. You will have to spend much more time thinking and planning up front, to make sure you arrive at the right place on time.

Speaking of time, deadlines cause less worry when you work long hours. If you hit your deadline, great. If you didn't, well, you worked long and hard, and who can blame you if you failed?

If you work fewer hours, deadlines are a constant gnawing presence, always getting closer. You will need to plan for them well in advance, always asking questions, on the lookout for unstated requirements and forgotten deliverables. And sometimes you'll be forced to find new solutions so you can hit those deadlines in time-and, of course, sometimes you will fail to find those solutions. And then you'll look bad, because you didn't work on the weekend, so whose fault is it the deadline was missed?

Your value

When you work long hours, it's easier to demonstrate how valuable you are to your boss: you were there on the weekend, after all. If you work fewer hours, well, who can say you're really getting much done? Did you deliver anything of value? How will you prove it?

Even worse than your boss is your own self-image. When you work long hours, your self-worth is about your work: you work hard, and that at least is something to be proud of, even if the project failed. If you work fewer hours you won't be able to feel proud of all the hours you worked. You'll be forced to consider the results, the outcomes: if you failed to deliver, you failed.

From comfort to effectiveness

Go through all this and- you'll become effective.

Valuing outcomes is not comfortable, but it is empowering. And good day or bad, you get to go home at a reasonable hour and do whatever you feel like. Which feels pretty damn good too.

You don't have to take my word for it, either: it's easy to try out. If you're working long hours, try spending a month working 40 hours a week, no more. Once you can no longer rely on working longer hours to solve all your problems, you'll soon find yourself approaching your work very differently.

And if you want a head start on learning these skills, read my book, The Programmer's Guide to a Sane Workweek.

11 Feb 2018 5:00am GMT

02 Feb 2018

feedPlanet Twisted

Moshe Zadka: The Python Toolbox

I have written before about Python tooling. However, as all software, things have changed -- and I wanted to write a new post, with my current understanding of best practices.


As of now, pytest has achieved official victory. Unless there are overwhelming reasons to use something else, strongly consider using it as your test runner. The only good reason is an existing project, with an existing test runner -- and even there, checking if pytest will just run your tests as is is worthwhile.

Even when using Twisted, unless you are implementing a new reactor, tests should be using in-memory reactors -- so the usefulness of trial is limited.

Static checking

In the static checking arena, flake8 and pylint are both still going strong. There are less and less reasons not to use both, especially if starting a project from scratch.

The flake8 plugin ecosystem is rich, and it is useful to look around and see if useful things are there. For example, the ebb-lint plugin is extremely strict about coding conventions -- hard to introduce to existing code bases, but wonderful when starting out a new one.

In the meantime, pylint has decent static code flow analysis which can often prevent bugs. Note, however, that Python static code analysis is hard, and pylint is not perfect. For example, it will often strugle with attrs-based classes.

Last but not least, mypy has made a showing in the field. It supports both Python 2 an 3, and allows annotating functions with types, in order to find mismatches before running the code. This is especially useful at API "boundaries", where the unit tests tend to cross less.

Test metarunners

The tox testing system is still the golden standard in Python. It can test complicated dependency matrixes, and allows configuring test commands flexibly. Its documentation is somewhat lacking, sadly -- it is often the case new tricks are only apparently after reading someone else's tox file.


Building wheels, especially if the project has no native-code extensions, is nowadays considered standard. The best place to build wheels is in tox, when configuring a test that will build a wheel, install it, and then test against the installed wheel.

The best and most reliable way to upload wheels, and source distributions, to PyPI is to use twine. It used to be a good idea to test against the test PyPI server, but nowadays it is best to set up a devpi server for local testing.

When building applications, pex is a great output format. It allows a one-file install.


The future is bright -- pip 10 is slated to come out, supporting the pyproject.toml format -- and hopefully the next post in the series will explain how to make packages using flit, with no setup.py.

02 Feb 2018 6:20am GMT

01 Feb 2018

feedPlanet Twisted

Itamar Turner-Trauring: Learn these programming skills before your inevitable death!

There is so much to learn as a programmer it's hard to even know where to begin. And even if you do begin, there's always something newer and shinier to distract you, and so you end up making these giant lists of things to learn and they get longer and longer and longer and you feel like shit about it but really you don't have the time to learn all of it, now do you?

So, why not take a few minutes to stop worrying about the things you should be learning, and instead let's talk a little about all the things you don't need to learn. And maybe when we're done you'll feel a little better.

But first, let's talk about-


We're all gonna die (eventually)

Someday you're going to die. So will I. So will everyone else, our friends and enemies both.

Typically one measures one's lifespan in years or days, but I once went and measured it in books. I did the math and figured out how many books I could read before I reached my presumptive death from old age. At the time I was reading about two books a week, but even so the number didn't seem anywhere near sufficient.

And having started down this morbid path, I arrived at an even worse place. Every time I read a book I'd get to thinking: "Is this book worth reading before I die? Shouldn't I be reading something more edifying than this entertaining yet trashy novel? Isn't re-reading a book a complete waste of my time?" Instead of enjoying the book I was reading, I was worrying about some other better book I could have been reading instead.

Eventually I got over it. I won't be able to read every book I want to before I die. Neither will you.


It's not so bad, though. When you're lying there dying you'll probably be thinking about the friends and family you'll miss. Or maybe you'll just be tired, and looking forward to an end to your pain and sorrow. Or, if you're having a really bad day, you'll be thinking that you shouldn't have had that last drink before driving home-don't drink and drive, kids. Better yet, don't drive at all; commuting is a terrible way to spend your life.

In any case, when it's time for you to die you probably won't be worrying about the books you haven't read. And as you lie on your deathbed, looking back at your life, you definitely won't be worrying about that new JavaScript framework you didn't get to play with.

Some skills you don't need to learn

There are many skills I do think you should learn (I have a whole pile of posts on this here website, in fact), but honestly-it's just software. If you don't learn these skills before you die, that's really not a big deal.

Software is a tool: tools are useful, and important, and you need them to build many things. But our tools are there to serve us, we should not be serving our tools.

Not to mention all the skills you really don't need to learn.

You don't need to learn every blindingly shiny new technology that will End Poverty and Bring Peace to Humanity. It probably won't do either, and quite possibly it won't turn out to be good for much at all. I started my career programming building multimedia CD-ROMs, which were really hot for about 6 months in the mid '90s, and somewhere in a landfill there's still boxes of old unusable CDs I worked on that no one cares about.

You don't need to learn everything programming language, certainly not in your spare time. You can and should learn those on the job, as and when they become useful.

You don't need to learn how to use every new library, tool, or framework. Just knowing they exist is usually more than enough: when and if you need them, you'll know they exist and go learn them then.

Some things to do before you die that are more important than learning another programming skill

Spend more time with your friends.

Spend more time with your family (unless you don't get along, sorry).

Eat good food.

Visit UNESCO World Heritage sites.

If you haven't seen one, a full solar eclipse is amazing.

Make the world a better place, even if it's just a little.

Whatever you think is important and worthwhile.

01 Feb 2018 5:00am GMT

30 Jan 2018

feedPlanet Twisted

Itamar Turner-Trauring: Not an expert? You can still teach

So your manager stops by and says "hey, we've got some new employees starting in a month, and you know SomeTechnology best, I'd like you to get them up to speed." And you nod and smile and feel the impostor syndrome kicking in: you don't know how to do this.

Software is complicated. Sometimes even when you've been using a tool or a language for a year or two, you might only know a small part of the functionality. It's already tough and intimidating to teach as it is, it's even worse when you're not confident in what you know. How can you teach when you're not an expert?

But as it turns out, being an expert can impede your ability to teach. You can become a better teacher by taking advantage your lack of expertise.

The problem with being an expert

Experts can actually make worse teachers. Specifically, experts often suffer from "expert blind spot", where their own knowledge blinds them to the way their students are thinking (I first learned of this concept from the book How Learning Works).

Experts differ from beginners in a number of ways that impact learning.

  1. Experts have much denser and interconnected conceptual models. Things that are obviously related to them are not at all obvious to beginners, who have sparsely connected conceptual models.
  2. Experts will skip steps, doing certain things so automatically they don't even realize they're doing them. From the beginners' point of view this results in unexplained jumps.
  3. Expertise is often unconscious. When asked, experts may not be able to explain why they're doing what they're doing, even if they know it's the right thing.

As a result, being an intermediate learner, where you know how to do a task but still need to consciously walk through the steps, can actually make you a better teacher.

Teaching when you're not an expert

Since you're not an expert, you don't need to pretend to be one. Instead you can teach the valuable knowledge you do have: the combination of the understanding of the technology, and the understanding or recent memory of how beginners think.

By showing how to deal with mistakes, and by admitting mistakes to your students, you're also making the topic less intimidating. Unlike some experts, who get confused and perhaps annoyed when mistakes happen-they never make those mistakes after all-you are giving your students the confidence that they too can work through problems. (Thanks to reader Jake for this point.)

Go teach!

Teaching doesn't need to be scary. It can just be you sitting down at a computer and saying "this is tricky, but I've figured out some ways to get things done, and so can you. Let me show you how."

This also applies to teaching more broadly. Every once in a while you'll see a conference call for proposals, and you'll say to yourself "I'm not an expert, I can't teach anything." But the truth is you can: your perspective as an intermediate learner is often much more valuable to beginners than that of an expert. Submit a talk proposal even if you're not an expert: you too have a valuable perspective.

30 Jan 2018 5:00am GMT

23 Jan 2018

feedPlanet Twisted

Itamar Turner-Trauring: How to get a job with a technology stack you don't know

Have you ever read an amazing-sounding job posting, and then felt that sinking feeling in your stomach when you reached the list of required technologies? Maybe you're a Python programmer, and they use Ruby on Rails; maybe you're mostly a front-end developer, and they want back-end skills. Whatever the missing technologies are, this is an awesome job you don't have a chance of getting.

Or do you?

In fact, it is possible, albeit not always easy. Years ago I got a job writing C++, when all I knew was Python and Java. And for the past few months I've been doing scientific computing for the first time, with a new toolchain, and math skills I haven't used in almost 20 years.

In this post I'll cover:

Apply anyway

Even if you feel you're not fully qualified for a job, you should still apply:

First, the list of technologies may be irrelevant. Sometimes the technologies listed are things the company might want to use someday, not what they actually use today. Sometimes they are perfectly happy hiring candidates with different technologies, and they put the list of technologies down because they aren't very thoughtful about how they write job ads.

But what if they do actually want those technologies? The list of technologies and skills is what the company would like in the ideal world, not necessary what they can get in practice. In the ideal world many companies would probably also like to pay you half as much and have you be twice as experienced, with the ability to create gold out of lead and summon unicorns at will. In practice, companies hire the candidates they can get, not the magical and often non-existent candidates they dream of.

Finally, technologies aren't everything. There are many other skills you have as a programmer, and some of them may trump the particular technologies you lack. We'll revisit this in the section on pitching yourself.

Which companies to apply to

It's hard to say as an outsider which companies will be more flexible, but here are some things to look for:

How to pitch yourself

Once you've picked the companies to apply to, you want to customize your cover letter, resume, and if you get there your presentation at the job interview. Here are some ways to do that:

The key is to research the company, try to understand their needs, and then demonstrate you can have value to them beyond just the list of technologies you know.

Next time you're looking for a job, don't limit yourself only to jobs with a technology stack you know. Look for jobs that excite you, for jobs you think you can do with just a little ramp-up time. And then apply for those jobs, knowing that most of them will ignore you-but it only takes one yes to get an exciting new job, and an exciting new opportunity to learn new skills.

23 Jan 2018 5:00am GMT

18 Jan 2018

feedPlanet Twisted

Itamar Turner-Trauring: The worst kind of resume is a list of technologies

Are you having a hard time getting responses to your resume? Do you know you have the skills for a job, but have a hard time convincing the company to hire you?

If your resume starts out with a long list of technologies you are selling yourself short. Knowing and using programming languages, libraries, and so on is a critical job skill for a software developer, but it's only part of what makes a good programmer. And the skills you aren't mentioning may well be keeping you from getting hired, even if you already have them.

In this post I'll discuss:

The most important part of your resume

Recruiters spend very little time reading resumes, and more broadly people tend to skim when reading. That means the first thing a reader see when they read your resume will have the most impact. The lower on the page, the less likely it is to be reached.

You should imagine the hiring manager as looking for some hint or phrase that will make them think "aha, this sounds promising, I should keep reading." And you should also imagine them giving up looking after less than 10 seconds.

That means you need put the most important pieces of information at the very top of your resume. The first sentence, the first paragraph, no lower. Your goal isn't to convey everything, you just want to make yourself sound interesting and relevant enough that the recruiter keeps reading.

For example, let's say you worked in bioinformatics two jobs ago, and you're applying to a bioinformatics job again. Your opening paragraph should mention your biotechnology work; that way the reader will be motivated to keep reading. Having given that motivation, you can still do the normal reverse chronological job history in the second part of your resume-but perhaps the paragraph for your current job should be a little shorter if it's less relevant.

Don't lead with a list of technologies

Since you need to make yourself sound interesting in the first few seconds, a list of technologies is a bad way to start. Merely claiming to know a technology doesn't tell the hiring manager how useful of an employee you'll be.

In some jobs knowing particular technologies will give you a head start, which is why some recruiters foolishly use technology keywords as a filter, but it's never really enough to do your job as a programmer. So spending precious moments of attention listing the technologies you know is a bad way to convey your value:

What to do instead

Instead of opening with a list of technologies, open with a paragraph demonstrating the ways in which you're a valuable employee, ideally tailored to the company you're applying for. Specifically, you want to convince the hiring manager you can do the job they're hiring for, which is either solving problems, or at more experienced levels identifying and solving problems. Writing software is merely a means to that end.

So you want a starting paragraph that emphasizes:

And you want to include just enough real-world examples that you will convince them to keep reading. Once you've got them reading the main job-listing section of your resume you can go into much more detail.

You can still have a list of technologies if you want, but don't waste the precious first half page of your resume on it. Personally I don't bother: I just mention names of relevant technologies at the jobs where I used them.

If you're currently looking for a job, go look at your resume, set a timer for 10 seconds and read it from the start. What will the recruiter learn about you? And is that all you want them to know? If all they've learned is that you know tool X or language Y, it's time to make some changes.

18 Jan 2018 5:00am GMT

08 Jan 2018

feedPlanet Twisted

Itamar Turner-Trauring: How to become a part-time programmer: an interview with an expert

For some people, a 40-hour workweek is something to aspire to; for others, it's still too much time taken up by a job. If you fall into that second category, if you want more time for hobbies, family and friends, or working on your own software projects, you too might dream of working less than full time.

But how do you get there? Almost no one advertises part-time programming jobs-believe me, I've me looked.

The answer: negotiation. I've negotiated a shorter workweek a few times myself, and I've met other programmers who have done so as well, some with just a few years of experience. And of all the programmers I've met who've negotiated part-time work, Mike's record is the most impressive.

Mike has spent pretty much all his career working part-time: he's been working part-time for more than 15 years. To help you get to a shorter, saner workweek, I sat down to interview Mike about how he does it.

Q. What does a sane workweek mean to you?

MIKE: Well, I only ever worked full time for about 1 year, and I learned pretty quickly that a sane workweek for me was less than 40 hours a week. I guess it's up to each individual, but I think most of us are forced to work more than we'd like, and at least for me 30-32 hours is better.

I want to work on average less, but I make it clear [when starting a job] that [I understand] things happen, stuff needs to get done. I would definitely work longer hours here and there.

Q. How did you realize you wanted to work less hours?

MIKE: Part of the reason I decided to demand this so early was, I started that first job when I was in university, and I stayed on for several years part-time while I was school. My contract was 10 hours a week, not very much but I was also going to classes and had to do homework and shit. I suppose that got me used to being able to go cycling or climbing or hiking on fairly short notice.

They were terrible at planning at this company, when a contract deadline was coming up everyone was working 60 to 70-hour weeks, having dinner at the office all the time. I wasn't forced to get caught up in that, since I had my excuse of going to school. I worked a lot more than 10 hours I was contracted to, though.

I saw this cycle there a lot, where managers would pull numbers out of their ass and promise them to clients, and then all the programmers were panicking for the last month. The panic mode of getting this done. [My feeling is] I'm not committed to those numbers you pulled out of your ass to tell your client, so partly it was reaction to that, seeing these people spending their entire lives at the office. I wanted to carve out my time early on.

Q. So how did you end up part-time after that first year?

MIKE: At that I job I tried to quit.

But they basically offered me more money, so I was like, "what if you gave me 75% of that, and I worked less?" And I guess they wanted to keep me around and they went for that.

At that job I was on payroll as a full time employee, but I got a bunch more holidays. So I got a quarter of my time in holidays; 72 days off a year? I was constantly booking time off, which was interesting.

That was how I landed my first part time thing. And then I did eventually quit that company and worked elsewhere, but I had found a new job while I was still in a part time situation, so it was a lot easier to demand a similar deal going forward.

Q. How many companies have you done this with? How many part time jobs?

MIKE: A bunch. All of my jobs. 7, no, 8.

(Mike goes off to look at his resume)

If you count the two I have now, two part time contracts, then 9.

Q. How exactly did you negotiate for shorter hours at later jobs?

I have several interviews here and there. And sometimes-if it's a company where I'm meh, not that serious about or interested in-I'll send them an email early in the process saying "hey I want to work part time." And then if they won't go for it I won't bother.

If I definitely wanted to work there, I'd go for the interview without telling them [I wanted a shorter workweek]. And if I got back for subsequent interviews or I got an offer I'd say "now I'm working 75%, I want to work part time somehow, I'm open to various different arrangements, I'm interested in working with you, lets work something out." Mostly if the companies were in the job offer stage they'd consider it very seriously. One was "no, no way," they didn't want to talk to me anymore. Mostly they're interested in negotiating somehow.

Q. What kinds of counter-offers did you get?

MIKE: Sometimes it was stuff like "I want to hire you, how do I sell this management? Help me sell it to management." That job took me 6 months to get from interview to legitimate part time job offer. That was the longest, and also unbeknownst to that company I'd been laid off: I'd started negotiating when I had a job, and was subsequently laid off. They wanted me to sell it to management. I said, "I don't want to work 5 days, how much happens Fridays? Not much? Then I'll work Monday to Thursday."

Usually I negotiated the full-time salary first, and then the details of pro-rating later: mostly it was about the details, once you'd convinced someone you were worth having. The easiest ones to negotiate are the ones which are 80% time, especially one day a week off. Usually I'd say Monday or Friday, and get a longer weekend, go to the mountains. But one of the people I inspired got himself an 80% contract, and he said "you've got to take Wednesday off." With Wednesdays, you only ever work two days in a row. It was awesome.

I always set expectations: "you're getting the best 4/5ths of my time, but only 4/5ths. I'm not going to pound out as much code." Realistically you kinda do, but the expectation should be if you're not there Wednesdays you shouldn't be doing as much work. That's part of the argument, that you're doing almost as much useful work.

Q. Did you find asking for a shorter workweek got easier over time?

Yeah, for sure, it definitely got easier. After the first couple times I felt more confident asking in the first place. It got easier in that sense.

Q. When you tell people you don't work full time, how do they react?

It's still considered weird by a lot of my friends, but I also get the other reaction, "I wish I could do that." Some people when you start new jobs, once you'd explained why you weren't there Wednesday, they'd say "I totally want that" but then I'd say I only get paid 80%. Once they'd realize they'd get paid less, [they'd say] "I'm not doing that."

Other people would say "cool, I want that." Definitely people I've worked with over the years have been inspired to do that, which is pretty nice.

Q. Why was the lower salary not an issue for you?

MIKE: I don't know, I guess I decided early on free time was more important than more money. Programmers are paid pretty well in my experience, 80% of a programmer job is plenty of money to get by on. Typically it's a lot more than what a lot of people are getting.

For me it was putting a premium on my time, and wanting to have that time to do other things. I've got hobbies, always had hobbies, different sports over the years which takes time. But even just stuff like having time to work on your own programming project, which I think is really valuable. Valuable enough to me that I'll actually pay money for it in the form of taking less salary.

I definitely don't have any regrets for doing that.

Q. Any final advice?

MIKE: My biggest piece of advice is that you have to be willing to quit your job to get a sane workweek, or you won't sound convincing when you ask for it. If you're looking for a new job, just ask, and if you're still at a job, then you're in a better position to ask.

Just go for it!

Itamar here: while I agree that working less than full time is wonderful, it also isn't for everyone. Perhaps to you a sane workweek means working for yourself, or working remotely, or just getting a job where you can go home at 5PM.

But whatever a sane workweek means to you, the basics are the same. As in Mike's case, you need the skills to be productive and valuable, you need to be able to negotiate, and you need enough financial security to have a strong negotiating position.

If you want to learn more about the skills you need, sign up for my free 6-part email course on negotiating a saner workweek:

08 Jan 2018 5:00am GMT

07 Jan 2018

feedPlanet Twisted

Glyph Lefkowitz: Tips And Tricks for Shipping a PyGame App on the Mac

I've written and spoken at some length about shipping software in the abstract. Sometimes I've even had the occasional concrete tidbit, but that advice wasn't really complete.

In honor of Eevee's delightful Games Made Quick???, I'd like to help you package your games even quicker than you made them.

Who is this for?

About ten years ago I made a prototype of a little PyGame thing which I wanted to share with a few friends. Building said prototype was quick and fun, and very different from the usual sort of work I do. But then, the project got just big enough that I started to wonder if it would be possible to share the result, and thus began the long winter of my discontent with packaging tools.

I might be the only one, but... I don't think so. The history of PyWeek, for example, looks to be a history of games distributed as Github repositories, or, at best, apps which don't launch. It seems like people who participate in game jams with Unity push a button and publish their games to Steam; people who participate in game jams with Python wander away once the build toolchain defeats them.

So: perhaps you're also a Python programmer, and you've built something with PyGame, and you want to put it on your website so your friends can download it. Perhaps many or most of your friends and family are Mac users. Perhaps you tried to make a thing with py2app once, and got nothing but inscrutable tracebacks or corrupt app bundles for your trouble.

If so, read on and enjoy.

What changed?

If things didn't work for me when I first tried to do this, what's different now?

There are still weird little corner cases you have to work around - hence this post - but mostly this is the story of how years of effort by the Python packaging community have resulted in tools that are pretty close to working out of the box now.

Step 0: Development Setup

Get a good Python. Use Homebrew, and brew install python3. If you need python 2, brew install python2. Don't use the System python. Probably nothing will work.

You probably also want to use a virtualenv for development. This post is about how to build a for-real thing that other people can download, but part of the magic of Python is the interactive, real-time dynamic nature of everything. Running the full build pipeline every time you change a file or an asset is slow and annoying. However, there's a weird thing where certain parts of the macOS GUI won't work right (in PyGame's case, mostly keyboard focus) unless your code appears to be in an application bundle.

I made this dumb little thing which lets you fake out enough of this that the OS won't hassle you: you just need to pip install venvdotapp; venvdotapp inside the virtualenv where you're making your pygame app.

Finally: pip install all your requirements into your virtualenv, including PyGame itself.

Step 1: Make an icon

All good apps need an icon, right?

When I was young, you just popped over into ResEdit Resorcerer MPW CodeWarrior Project Builder Icon Composer Xcode and created a new ICON resource cicn resource .tiff file .icns file. Nowadays there's some weird opaque stuff with xcassets files and Contents.json and "Copy Bundle Resources" in the default Swift and Objective C project templates and honestly I can't be bothered to keep track of what's going on with this nonsense any more.

Luckily the OS ships with the macOS-specific "scriptable image processing system", which can helpfully convert an icon for you. Make yourself a 512x512 PNG file in your favorite image editor (with an alpha channel!) that you want to use as your icon, then run it something like this:

$ sips -s format icns Icon.png --out Icon.icns

somewhere in your build process, to produce an icon in the appropriate format.

There's also one additional wrinkle with PyGame: once you've launched the game, PyGame helpfully assigns the cute, but ugly, default PyGame icon to your running process. To avoid this, you'll need these two lines somewhere in your initialization code, somewhere before pygame.display.init (or, for that matter, pygame.display.<anything>):

from pygame.sdlmain_osx import InstallNSApplication

Obviously this is pretty Mac-specific so you probably want this under some kind of platform-detection conditional, perhaps this one.

Step 2: Just Include All The Dang Files, I Don't Care About Performance

Unfortunately py2app still tries really hard to jam all your code into a .zip file, which breaks the world in various hilarious ways. Your app will probably have some resources you want to load, as will PyGame itself.

Supposedly, packages=["your_package"] in your setup.py should address this, and it comes with a "pygame" recipe, but neither of these things worked for me. Instead, I convinced py2app to just splat out all the files by using the not-quite-public "recipe" plugin API:

import py2app.recipes
import py2app.build_app

from setuptools import find_packages, setup

pkgs = find_packages(".")

class recipe_plugin(object):
    def check(py2app_cmd, modulegraph):
        local_packages = pkgs[:]
        local_packages += ['pygame']
        return {
            "packages": local_packages,

py2app.recipes.my_recipe = recipe_plugin

APP = ['my_main_file.py']

    name="Your Game",
    options={'py2app': OPTIONS},
        "": ["*.gal" , "*.gif" , "*.html" , "*.jar" , "*.js" , "*.mid" ,
             "*.png" , "*.py" , "*.pyc" , "*.sh" , "*.tmx" , "*.ttf" ,
             # "*.xcf"

This is definitely somewhat less efficient than py2app's default of stuffing the code into a single zip file, but, as a counterpoint to that: it actually works.

Step 3: Build it

Hopefully, at this point you can just do python setup.py py2app and get a shiny new app bundle in dist/$NAME.app. We haven't had to go through the hell of quarantine just yet, so it should launch at this point. If it doesn't, sorry :-(.

You can often debug more obvious fail-to-launch issues by running the executable in the command line, by running ./dist/$NAME.app/Contents/MacOS/$NAME. Although this will run in a slightly different environment than double clicking (it will have all your shell's env vars, for example, so if your app needs an env var to work it might mysteriously work there) it will also print out any tracebacks to your terminal, where they'll be slightly easier to find than in Console.app.

Once your app at least runs locally, it's time to...

Step 4: Code sign it

All the tutorials that I've found on how to do this involve doing Xcode project goop where it's not clear what's happening underneath. But despite the fact that the introductory docs aren't quite there, the underlying model for codesigning stuff is totally common across GUI and command-line cases. However, actually getting your cert requires Xcode, an apple ID, and a credit card.

After paying your hundred dollars, go into Xcode, go to Accounts, hit "+", "Apple ID", then log in. Then, in your shiny new account, go to "Manage Certificates", hit the little "+", and (assuming, like me, you want to put something up on your own website, and not submit to the Mac App Store), and choose Developer ID Application. You probably think you want "mac app distribution" because you are wanting to distribute a mac app! But you don't.

Next, before you do anything else, make sure you have backups of your certificate and private key. You really don't want to lose the private key associated with that cert.

Now quit Xcode; you're done with the GUI.

You will need to know the identifier of your signing key though, which should be output from the command:

$ security find-identity -v -p codesigning | grep 'Developer ID' | sed -e 's/.*"\(.*\)"/\1/'

You probably want to put that in your build script, since you want to sign with the same identity every time. The command to do the signing is:

$ codesign -fs "${YOUR_DEVELOPER_ID_IDENTITY}" --deep "dist/${NAME}.app"

Step 5: Archive it

The right way to do this is probably to use dmgbuild or something like it, but what I promised here was quick and dirty, not beautiful and best practices.

You have to make an archive that preserves symbolic links. There are a few options for this:

Most importantly, if you use the zip command line tool, you must use the -y option. Without it, your downloadable app bundle will be somewhat mysteriously broken even though the one before you zipped it will be fine.

Step 6: Download it

Ideally, at this point, everything should be working. But to make sure that code-signing and archiving went correctly, you should have either a pristine virtual machine with no dev tools and no Python installed, or a non-programmer friend's machine that can serve the same purpose. They probably need a relatively recent macOS - I know that apps made using the above technique will definitely work on High Sierra and will definitely break on Yosemite; they probably start working at some OS version between those.

There's no tooling that I know of that can clearly tell you whether your mac app depends on some detail of your local machine. Even for your dependencies, there's no auditwheel for macOS. So it's always a good idea to check your final app build on a fresh computer before you announce it.


If you were expecting to get to the end and download my cool game, sorry to disappoint! It really is a half-broken prototype that is in no way ready for public consumption, and given my current load of personal and professional responsibilities, you definitely shouldn't expect anything from me in this area any time soon, or, you know, ever.

But, from years of experience, I know that it's nearly impossible to summon any motivation to work on small projects like this without the knowledge that the end result will be usable in some way, so I hope that this helps someone else set up their Python game-dev pipeline.

I'd really like to turn this into a 3-part series, with a part for Linux (perhaps using flatpak? is that a good thing?) and a part for Windows. However, given my aforementioned time constraints, I don't think I'm going to have the time or energy to do that research, so if you've got the appropriate knowledge, I'd love to host a guest post on this blog, or even just a link to yours.

If this post helped you, if you have questions or corrections, or if you'd like to write the Linux or Windows version of this post, let me know.

07 Jan 2018 8:48pm GMT

31 Dec 2017

feedPlanet Twisted

Moshe Zadka: Jupyter for SRE

Jupyter is a tool that came out of the data science community. In science, being able to replicate experiments is of the utmost importance -- so a tool where you can "show your work" is helpful. However, being able to show your work -- have colleagues validate what you have done, repeat it if needs be, and learn new techniques -- is also useful in the world of Site Reliability Engineering and DevOps.

The Jupyter console allows us to experiment (carefullly!) with APIs, running one function at a time, and validating the results. It allows building the needed automation from simple atoms, all the while learning how to use them.

The Jupyter Python kernel is popular in the data science community because so many data science libraries are available for Python. Luckily, the same is true in the SRE/DevOps community.

import github3
import os

The GitHub API has several client libraries in Python. My personal favorite is github3 -- I find its interface allowing remarkably idiomatic Python.

with open(fname) as fin:
    token = fin.read().strip()
gh = github3.login(token=token)

I have prepared a GitHub authentication token in a file. This allows the NoteBook to be published widely, without leaking access credentials. Never put usernames and passwords in Jupyter notebooks!

repositories = list(gh.organization('twisted').iter_repos())
repositories[:3], len(repositories)
([<Repository [twisted/txmongo]>,
  <Repository [twisted/twisted]>,
  <Repository [twisted/txaws]>],

This is a list of the repositories in the Twisted GitHub organization. It is nice to be able to validate we got a reasonable value by checking the first three. In previous versions of the notebook, my usage of github3 had an error -- and this was a list of all repositories I had access to, including private ones! Being able to inspect values interactively meant I could fix the bug easily.


As an example of why this might be useful, we are checking the commit hash of the trunk branch. This can be used in validating which version we are running somewhere, or checking if there have been new commits.

The GitHub API is big, and this is not meant to be an exhaustive guide to it. However, this approach is powerful -- it can be used, for example, to automatically create pull requests for a list of repositories. This comes in handy when needing to change the build structure, for example.

from fabric import api as fabpi

The Fabric library, (here used in its fabric3 fork) is an all-purpose ad-hoc library for operations.

Again, a full tutorial is beyond the scope of this article.

fabpi.local("uname -a", capture=True)

However, the advantages of running Fabric from Jupyter notebook are big. Because Fabric is specifically designed for ad-hoc operations, there is often no way to know exactly what someone did. Even with a fabfile, the logging is often lacking.

Running the functions from a notebook means an official log of what was done -- that can easily be attached to the relevant ticket, or to the post-mortem. (Either the post-mortem that the operations were meant to fix, or the ones they inevitably caused).

import docker
client = docker.DockerClient(base_url='unix://var/run/docker.sock')

The Docker client is also available as a Python library. Once again, the possibilities are endless.

[im for im in client.images.list() if (im.tags or [''])[0].startswith('debian')]
[<Image: 'debian:latest'>,
 <Image: 'debian:stable-slim', 'moshez/debian:2017-10-26T10-58-56-455022'>]
import boto3

The boto3 library is an API for the Amazon Web Services -- which includes everything from load balancers, through orchestrating containers, to sending e-mail.

The Jupyter console is a great adjunct to the AWS web console -- while results can often be inspected in the web console, any actions done from the notebook can be repeated, tweaked, and automated.

ec2 = boto3.client('ec2', region_name='us-west-2')


For a team of SRE/DevOps engineers who are already using Python, the Jupyter notebook allows a great way to communicate about actions taken. It logs the inputs and the outputs, while allowing editing and clarifying.

Note that it is not a useful auditing tool, and should not be used as such. It is meant as a communications tool, attaching notebooks to tickets or e-mails in order to clarify, in a way that can be fed back into a computer for testing and tweaking.

31 Dec 2017 3:30am GMT

Jonathan Lange: Eighty Percent

Hank Green recently shared the embarrassing secret to his productivity, which he summarises as:

Everything creative I do, I do my best to get it 80% of the way to as good as I can make it and go no further. I just don't try to get it to 100%.

I recommend watching the video or reading the transcript, as he does a great job of explaining why and how this works.

I want to try to adopt this attitude in 2018. I have prided myself-perhaps without justification-on producing high-quality work but I expend way too much time fine-tuning and end up writing, speaking, and coding less than I would like.

That said, there might be a difference between creative projects that get released and then abandoned and software engineering projects that get deployed and then maintained forever.

With software projects like that, there's an amazing power to continuously applying effort to the same code-base to make it incrementally better. Slow, steady, 80% efforts that acculumate over time to make something beautiful, maintainable and useful.

But you never know when the budget is going to be yanked from under you. In the worst case, you'll be on the hook for running something in production without having the time or opportunity to fix the problems you find.

It's the fear of this that sometimes drives me to reach for 100% as good as I can do. I guess the only thing I can do about this is ignore the fear.

Have you ever made conscious efforts to improve your productivity by lowering your ambitions around quality? How did it go?

31 Dec 2017 12:00am GMT

29 Dec 2017

feedPlanet Twisted

Hynek Schlawack: Conditional Python Dependencies

Since the inception of wheels that install Python packages without executing arbitrary code, we need a static way to encode conditional dependencies for our packages. Thanks to PEP 508 we do have a blessed way but sadly the prevalence of old setuptools and pip versions make it a minefield to use.

29 Dec 2017 12:00am GMT

18 Dec 2017

feedPlanet Twisted

Moshe Zadka: Write Python like an expert

Ten tricks to level up your Python.

Trick 0 -- KISS

Experts know about the weird dark corners of Python -- but do not use them in production code. The first tip is remembering that while Python has some interesting corners, they are best avoided in production code.

Make your code as straightforward as possible.

Trick 1 -- The power of lists

The humble list, or even humbler [], pack a lot of punch -- for those who know how to use it.

It serves, of course, as a useful array type. It is also a good stack, using append and pop(), with the correct (amortized) performance characteristic. The .sort() method is sophisticated enough it is one of the few cases where Python actually broke new theoretical grounds on a sorting algorithm -- timsort was originally invented for it.

Trick 2 -- The power of dicts

The humble dict, or even humbler {}, also pack a lot of punch.

While many use string keys, it is important to remember any immutable type is possible as keys, including tuples and frozensets. This helps writing caches, memoizers or even a passable sparse array.

The keyword argument constructor also gives it a lot of power for making simple and readable APIs.

Trick 3 -- Iterators and generators

The iterator protocol is one of the most powerful aspects of Python. Experts understand it deeply, and know how to use it to make code shorter, more readable, more composable and more debuggable.

One of the easiest ways to accomplish it is to write functions that accept an iterator and return an iterator: and remembering that generators are really good syntactic sugar for writing functions which return iterators.

If a code base has a lot of functions that return iterators, the iterator algebra functions in itertools become immediately higher value.

Trick 4 -- Collections

The collections module has a lot of wonderful functionality.

For code that needs defaults, defaultdict.

For code that needs counting, Counter.

For FIFOs, deque.

Trick 5 -- attrs

One thing that is not wonderful about the collections module is the namedtuple class.

In almost every way imaginable, the attrs package is better. Also, for things that wouldn't be namedtuples otherwise, attrs is still better.

Trick 6 -- First class functions and types

Return functions. Store them in lists, or dictionaries. Keep classes in a double-ended queue. These are not a "Python does what". These are ways to avoid boilerplate or needless indirections.

Trick 7 -- Unit tests and lint

Experts hate having to waste time. Writing unit tests makes sure they have to fix any given bug only once. Correctly configuring a linter makes sure they do not have to comment on every pull request with a list of nitpicks.

Trick 8 -- Immutability

Immutable data structures, such as those available from the Pyrsistent library, are useful for avoiding a lot of bugs. "Global mutable state is the root of all evil" -- and if you cannot get rid of things being global (modules, function defaults and other things) it is often possible to make them mutable.

Immutable data structures are much easier to reason about, and much harder to make bugs that are hard to find and trigger.

Trick 9 -- Not reinventing the wheel

If something is available as a wheel, don't reinvent it. PyPI has ~125K packages, at times of writing. It is almost certain that it has something that takes care of some of the task you are currently working on.

How to know what's worthwhile?

Follow Planet Python, check Awesome python and, if it is within reach, try to go to Python meetups or conferences. (If it's not, of even if it is, PyVideo has the videos -- but talking to other Python programmers is extremely useful.)

18 Dec 2017 6:00am GMT

14 Dec 2017

feedPlanet Twisted

Moshe Zadka: Interesting text encodings (and the people who love them)

(Thanks to Tom Prince and Nelson Elhage for suggestions for improvement.)

Nowadays, almost all text will be encoded in UTF-8 -- for good reasons, it is a well thought out encoding. Some of it will be in Latin 1, AKA ISO-8859-1, which is popular in the western world. Less of it will be in other members of the ISO-8859 family (-2 or higher). Some text from Japan will occasionally still be in Shift-JIS. These encodings are all reasonable -- too reasonable.

What about more interesting encodings?


Encodings turn a sequence of logical code points into a sequence of bytes. Bytes, in turn, are just sequences of ones and zeroes. Usually, we think of the ones and zeroes as mostly symmetric -- it wouldn't matter if the encoding was to the "dual" byte, where every bit was flipped. SSD drives do not like long sequences of zeroes -- but neither do they like long sequences of ones.

What if there was no symmetry? What if every "one" weakened your byte?

This is the history of one of the most venerable media to carry digital information -- predating the computer by its use in automated weaving machines -- the punched card. It was called so because to make a "one", you would punch a hole -- that was detected by the card reader by an electric circuit being completed. Punching too many holes made cards weak: likely to rip in the wear and tear the automated reading machines inflicted upon them, in the drive to read cards ever faster.

EBCDIC (Extended Binary Coded Decimal Interchange Code) was the solution. "Extended" because it extends the Binary Coded Decimal standard -- numbers are encoded using one punch, which makes them easy to read with a hex editor. Letters are encoded with two. Nothing sorts correctly, of course, but that was not a big priority. Quoting from Wikipedia:

"The distinct encoding of 's' and 'S' (using position 2 instead of 1) was maintained from punched cards where it was desirable not to have hole punches too close to each other to ensure the integrity of the physical card.

Of course, it wouldn't be IBM if there weren't a whole host of encodings, subtly incompatible, all called EBCDIC. If you live in the US, you are supposed to use code page 1140 for your EBCDIC needs.

Luckily, if you ever need to connect your Python interpreter to a card-punch machine, the Unicode encodings have got you covered:

>>> "hello".encode('cp1140')

If you came to this post to learn skills immediately relevant to your day to day job and are entirely not obsolete, you're welcome.


Suppose you're a Russian speaker. You write your language using the Cyrrilic alphabet, suspiciously absent from the American Standard Code for Information Interchange (ASCII), developed during the height of the cold war between the US of A and the USSR. Some computers are going to have Cyrrilic fonts installed -- and some are not. Suppose that it is the 80s, and the only language that runs fast enough on most computers is assembly or C. You want to make a character encoding that

  • Will look fine if someone has the Cyrrilic installed
  • Can be converted to ASCII that will look kinda-sorta like the Cyrrilic with a program that is trivial to write in C.

KOI-8 is the result of this not-quite-thought experiment.

The code to convert from KOI-8 to kinda-sorta-look-a-like ASCII, written in Python, would be:

MASK = (1 << 8) - 1
with open('input', 'rb') as fin, open('output', 'wb') as fout:
    while True:
        c = fin.read(1)
        if not c:
        c = c & MASK # <--- this right here

The MASK constant, written in binary, is just 0b1111111 (seven ones). The line with the arrow masks out the "high bit" in the input character.

Sorting KOI-8 by byte value gives you a sort that is not even a little bit right for the alphabet: the letters are all jumbled up. But it does mean that trivial programs in C or assembly -- or sometimes even things that would try to read words out of old MS Word files -- could convert it to something that looks semi-readable on a display that is only configured to display ASCII characters, possibly as a deep hardware limitations.


How lovely it is, of course, to live in 2017 -- the future. We might not have flying cars. We might not even be wearing silver clothing. But by jolly, at least our modern encodings make sense.

We send e-mails in UTF-8 to each other, containing wonderful emoji like "eggplant" or "syringe".

Of course, e-mail is old technology -- we send our eggplants, syringes and avocadoes via end-to-end encrypted Signal chat messages, unreadable by any but our intended recipient.

It is also easy to register our own site, and use an off-the-shelf SaaS offering, such as Wordpress or SquareSpace, to power it. And no matter what we want to put as our domain, we can...as long as it is ASCII-compatible, because DNS is also older than the end of the cold war, and assumes English only.

Seems like this isn't the future after all, which the suspicious lack of flying cars and silver clothing should really have alerted us to.

In our current times, which will be a future generation's benighted past, we must use yet another encoding to put our avocadoes and eggplans in the names of websites, where they rightly belong.

Enter Punycode, an encoding that is not afraid to ask the hard questions like "are you sure that the order encoded bits in the input and the output has to be the same"?

That is, if one string is a prefix of another, should its encoding be a prefix of the other? Just because UTF-8, EBCDIC, KOI-8 or Shift-JIS adhere to this rule doesn't mean we can't think outside the box!

Punycode rearranges the encoding so that all ASCII compatible characters go to the beginning of the string, followed by a hyphen, followed by a complicated algorithm designed to minimize the number of output bytes by assuming the encoded non-ASCII characters are close together.

Consider a simple declaration of love: "I<Red heart emoji>U".

>>> source = b'I\xe2\x9d\xa4U'
>>> declaration = source.decode('utf-8')
>>> declaration.encode('punycode')

Note how, like a well-worn pickup line, I and U were put together, while the part that encodes the heart is at the end.

Consider the slightly more selfish declaration of self-love:

>>> source = b'I\xe2\x9d\xa4me'
>>> source.decode('utf-8').encode('punycode')

Note that even though the selfish declaration and the true love declaration both share a two-character prefix, the result only shares one byte of prefix: the heart got moved to the end -- and not the same heart. Truly, every love is unique.

Punycode's romance with DNS, too, was frought with drama: indeed, many browsers now will not display unicode in the address bar, instead showing "xn--<punycode ASCII>" (the "xn--" in the beginning indicates this is a punycoded string) as a security measure against phishing: it turns out there are a lot of characters in Unicode that look a lot like "a", leading to many interesting variants on "Paypal.com" and "Gmail.com", which look indistinguishable to most humans -- and turns out, most users of the web are indeed of the homo sapiens species.

14 Dec 2017 4:00am GMT

11 Dec 2017

feedPlanet Twisted

Moshe Zadka: Exploration Driven Development

"It's ok to mess up your own room."

Sometime there is a problem where the design is obvious -- at least to you. Maybe it's simple. Maybe you've solved one like that many times. In those cases, just go ahead -- use Test-Driven-Development, lint your code as you're writing, and push a branch full of beautiful code, ready to be merged.

This is the exception, rather than the rule, though. In real life, half of the time, we have no idea what we are doing. Is a recursive or iterative solution better? How exactly does this SaaS work? What does Product Management actually want? What is, exactly, the answer to life, the universe and everything?

A lot of the time, solving a problem becomes with exploratory programming. Writing little snippets, testing them out, writing more snippets, throwing some away when they seem to be going down a bad path, saving some from earlier now that we understand the structure better. Poking and prodding at the problem, until the problem's boundaries become clearer.

This is, after all, why dyamic languages became popular -- Python became popular in web development and scientific computing precisely because in both places, "exploratory programming" is important.

In those cases, every single rule about "proper software development" goes straight out the window. Massive functions are fine, when you don't know how to break them. Code with one letter variables is fine, when you are likely to throw it away. Code with bad formatting is fine, when you are likely to refactor it. Code with no tests is fine, if it's doing the wrong thing anyway. Code with big commented out sections is fine, if those are likely to prove useful in an hour.

In short, every single rule of "proper software development" goes out the window when we are exploring a problem, testing its boundaries. All but one -- work on a branch, and keep your work backed up. Luckily, all modern version control systems have good branch isolation and easy branch pushing, so there is no problem. No problem, except the social one -- people are embarrassed at writing "bad code". Please don't be. Everyone does it. Just don't merge it into the production code -- that will legitimately annoy other people.

But as long as the mess is in your own room, don't worry about cleaning it up.

11 Dec 2017 4:00am GMT

07 Dec 2017

feedPlanet Twisted

Itamar Turner-Trauring: The junior programmer's guide to asking for help at work

When you're just getting started as a programmer and you need help frequently, asking for help can feel daunting, like you'll lose either way. Ask too soon and you'll end up feeling stupid for not having figured out the answer on your own. And if you don't ask for help, your manager can get annoyed that you're taking too long to solve the problem.

Asking for help is a skill, and a skill you can learn. Once you've mastered this skill you will be able ask questions at the right time, and in the right way. In this post I'll cover:

The wrong way to ask for help

There are two main failures when asking for help, asking too much and asking too little.

"Help help help help help help help help": You will of course have many questions when you're learning a new codebase or a new technology. But if you're asking your lead developer a question every 10 minutes, you're going to annoy them. A lot. You're impeding their ability to work, and you're probably not spending enough time learning on your own.

Instead of asking your questions one by one as they occur, write them all down. Then, when your local expert seems to have a free moment, or if it's been a few hours since you last asked a question, go and ask them all your questions at once. This will be less intrusive, and chances are you will have figured out some of the answers on your own in the interim.

"I don't want to ask for help!": Asking for help can be embarrassing, it's true. And trying to figure stuff out on your own can help you learn. But if you wait too long, or never ask for help, you'll both learn less and annoy your manager, because inevitably you'll end up spinning your wheels and wasting time.

Instead, wait until you've given it a reasonable try, and then ask. You'll learn how to do that in the next section.

Knowing when to ask for help with timeboxing

So how exactly do you know when to ask for help? Advance planning. By knowing how long you have to spend on the task, and then setting a timebox, a limited amount of time to work on it on your own, you can have an alert (metaphorical or real) telling you "it's been too long, time to ask for help."

Here's how the process works:

  1. When your lead developer gives you a task, ask how much time you should spend on it. They might say something like "we need that ready in a couple of days, but really it should only take you a day." So now you know you want to aim to finish the task within a day. (Over time you'll learn how to do this yourself, and also whether your manager is overly optimistic or pessimistic about their estimates.)
  2. Now that you know your deadline, set a timebox, a limited amount of time that is less than your deadline. If your deadline is a day, you might set it to three hours.
  3. Now start your task. After you hit your timebox (e.g. three hours), see where you're at: are you making good progress? Great, set another timebox and keep working. Not making progress? It's time to ask for help.

If your deadline is one day, and you ask for help after three hours, you've not asked too late: there's still time to finish the task. And you haven't asked too soon, either, you've at least tried on your own.

Learning more (and looking good) when you're asking for help

You've hit your timebox, and you're asking for help: how do you get the most value out of your questions?

Don't ask yes/no questions: "is this how I do this?"

If your lead developer actually answers with "yes" or "no", you're only gaining 1 bit of information, the smallest amount of information possible. Instead, ask open ended questions: "what should the result be like?" "can you walk me through how this works?", etc.

Always present a potential answer the question.

It doesn't have to be the best answer, or the correct answer (if it were, you probably wouldn't be asking for help, after all). But you should always say something like "my best guess is this works like this, because of X and Y, but I'm still a little confused - could you explain this?"

Providing an answer serves multiple purposes:

  1. It forces you to try to come up with an answer and learn more. Sometimes you'll figure it out on your own!
  2. It demonstrates to your manager that you made an effort, making you look good.
  3. It helps your manager understand what you know and what you don't, which means they'll have an easier time helping you.

How to ask for help: a recap

Here's the short version:

  1. Do ask for help.
  2. Batch up your questions.
  3. Set a timebox on tasks, and ask for help if you hit the timebox and you're still stuck.
  4. Ask open-ended questions, and always provide a potential answer.

Next time your manager gives you a task, apply these guidelines: they'll be happier, and you'll learn more.

07 Dec 2017 5:00am GMT