The Brilliant Disaster by Jim Rasenberger

This is an incredible story that is so much more complex than is capable of being understood just from popular knowledge about the famous events involved.

It’s a timely book to read and will continue to be relevant as we continue to discover more and more negative effects of the USA’s involvement in other countries affairs.

Chasing Space by Leland Melvin

The path astronauts take to space is not always a direct route, and no one can speak to that truth more than Leland Melvin, the only professional football player to also fly in space and visit the International Space Station.

This book is a must-read for those interested in the space program, but not for the reasons one might expect. Our nation and world needs, more than ever, to hear stories about the challenges people of color and other minorities face to get to the places white people have been from the beginning. Leland Melvin tells that story well and we should listen.

Kubernetes: Up and Running by Kelsey Hightower, Brendan Burns, and Joe Beda

Kubernetes has been one of the hottest technology topics of the year. The authors of this book have been around the scene since the very beginning. This is a short book, perfect for ensuring you know the core concepts of, and have a basic familiarity with, Kubernetes.

There is obviously much more to learn, but having confidence in your base knowledge is well worth the time. In fact, I am now purchasing other books in the O’Reilly “Up and Running” series expecting to see similar benefit.

Cloud Native Infrastructure by Justin Garrison and Kris Nova

The technology world is constantly changing and those of us who deal with software infrastructure would do well to read this book. Unlike Kubernetes: Up and Running, you won’t run to the command line and immediately put to use the knowledge from this book. However, after reading this book you will think about the changing trends of this industry with a bit more clarity.

I find myself frequently thinking back to nuggets of information from this book when weighing decisions for new software project architecture, and likely will for some time.

A Room of One’s Own by Virginia Wolf

If you adjust the currencies for the present day (£500/yr won’t really cut it anymore), you’d be hard pressed to find any part of this book that isn’t just as relevant today as it was almost 90 years ago. Like the stories from people of color, we need to listen to stories from women just as much today as in 1929.

Wolf’s writing style is wonderful: elegant, flowing, deep, and complex. I’d like to think I recognize elements of it in the writing of talented women I read today. It would makes sense that this is true.

The Manager’s Path by Camille Fournier

This is one of those books where you are actually reading about yourself. Hopefully, it’s in the incredibly useful descriptions of how to be a good employee/manager/CTO/etc that are in this book.

Most likely, the toughest but most useful parts of this book will be when you see a bit of yourself in the “Good Manager/Bad Manager” sections that detail various levels of unhelpful behavior that all sorts of team members can exhibit. It was definitely true for me, but that’s part of what makes this book so helpful.

The Secret Race by Tyler Hamilton and Daniel Coyle

We all knew professional cycling was full of performance enhancing drugs. But there was always a shroud of mystery and just enough unknown to ignore it or make it not worth thinking about. Obviously that’s no longer true. Tyler Hamilton does an incredible job with a first hand story that gives all the details of what being a top level pro cyclist was REALLY like.

It may not really make pro cycling appealing, but if you ever thought about living in Girona, Spain, you will think about it even more after this book.

Lance Armstrong’s War by Daniel Coyle

I read this book many years ago (before I was writing about the books I read). Back then, I treated it like a bible. What you wanted to aspire to, how you should act, if you wanted to become a true cyclist.

I don’t feel that way anymore. The second time reading this book, I read it as a companion to The Secret Race. When Coyle wrote this book, he could only hint at the things he knew about the real state of professional cycling. And he didn’t know nearly as much as we all do now.

Reading these two books is a great combo. One is direct with every detail. Lance Armstrong’s War is best if you read behind the lines. Most of the wild speculation about how corrupted professional cycling might be turned out to be true.

Long Walk to Freedom by Nelson Mandela

This year, I didn’t write my reading list in the order I completed books, because I had to save this one for last. Without a doubt, this is the best book I have ever read.

Nelson Mandela tells a story with a unique blend of clarity, emotion, humor, and care. And the story he has to tell is one of the most important of the 20th century.

Throughout this book I was brought to laughter, and to tears. I felt hope and despair. I was along for the entire journey with Mandela and 40 million South Africans.

As an added bonus, I read much of this book while in Cape Town, South Africa. It is not lost on me that while I was reading, I was smelling the exact same ocean air that Mandela was smelling when he wrote much of it from a few miles away on Robben Island.

After I was done, I spent hours reading other accounts. A huge treasure we have today is that there are countless videos of Mandela available instantly on the internet. Some of them cover his speeches or other events he wrote about in the book. I can confirm that his incredible wit, charm, and unstoppable vision is as present when he is speaking live as when he has endless hours in his cell to write down his thoughts.

I can’t recommend enough a trip to South Africa and a read of this book. But if the cost of flying almost to one end of this Earth is enough, at least read the book.

Despite having most of my configs in a git repository or otherwise tracked, I ran into a problem with setting this up.

Here’s the error:

1
2
3

$ git commit
error: gpg failed to sign the data
fatal: failed to write commit object

And the answer (for me):

Make sure the user.signingkey option in your .gitconfig is in the correct format! This is very silly, but there are some easy ways to get it wrong. First, some correct examples.

Standard long key format (recommended)

1
2
3
4

[user]
    name = Julian Simioni
    email = julian@simioni.org
    signingkey = 0x4CEEB1E5A7FD15E1

That’s 0x followed by the last 16 characters of your key id. At least as of gnupg 2.2.0 its the standard output of a command like gpg --list-secret-keys

Long key format without the hexidecimal prefix

1
2
3

[user]
    # ...
    signingkey = 4CEEB1E5A7FD15E1

Still 16 characters, but without the prefix clarifying that the value is written in hexidecimal.

Short key format (works, but not recommended)

1
2
3

[user]
    # ...
    signingkey = A7FD15E1

This is the “short” format, consisting of only 8 characters. It works too, and was much more standard in the past. However its not recommended as its now far too easy to generate keys that have the same final 8 characters.

DOESN’T WORK: other key lengths

1
2
3

[user]
    # ...
    signingkey = CEEB1E5A7FD15E1

You might be assuming, like I did, that GPG and git would be smart enough to allow you to use any suffix of your key, much like git allows you to use any unique prefix of a git commit hash. That is not the case. I suppose it makes sense. Oh well.

Other useful debugging steps

While in my case the issue with my commit signing was simple user error, I did go through quite a few other debugging steps, and they were helpful in figuring out where the error was not! Here they are in case they are useful to me again later (quite likely), or others.

Many of these came from this helpful Stackoverflow thread.

Ensure basic encryption works

A simple way to test gpg and your secret key itself is to issue a command like the following:

1

echo "test" | gpg --clearsign

This will send a small bit of text (“test”) to gpg, and have it print out the same text, but with a plaintext signature attached. If it works, then you know quite a few things are working: gpg itself, your secret key, whatever method you are using to enter the passkey to your key (if you have one, which you should!), etc.

GPG Agent settings, or lack thereof

GPG internally uses an “agent” program. Basically, whenever you run gpg, it launches a process in the background that will stick around. That process is used to remember your passphrase temporarily, for convenience, and probably other things.

In the past, ensuring the gpg command you run on the command line can communicate with this agent has been challenging. If you’ve ever seen instructions regarding adding various GPG_AGENT_INFO environment variables, its an attempt to properly set up this communication channel.

The good news is that as of GnuPG version 2.1.0, none of this is needed. There is now a “standard” method of connecting to the agent and everything is supposed to just work. Compare the instructions in the documentation for version 2.0 and the latest version to see what I mean.

GPG_TTY environment variable

This variable is important to set up. It will help GPG know which terminal it is running on, so that the prompt to enter your key passphrase is shown in the correct place. Again, from the GnuPG documentation, this will do the trick:

1
2

GPG_TTY=$(tty)
export GPG_TTY

Handling local terminal and SSH connections gracefully

There’s nothing worse than not being able to use gpg because you SSHed into your computer, and when you ran gpg, it popped up a dialog box to enter your passphrase on the computer display itself, rather than in your SSH session.

Fortunately, its easy to tell pinentry, the underlying program responsible for managing passphrase entry, to do the right thing during SSH sessions.

1
2
3

if [[ -n "$SSH_CONNECTION" ]]; then
    export PINENTRY_USER_DATA="USE_CURSES=1"
fi

This comes from the GnuPG Gentoo Wiki article.

Pretty fancy.

Moby Dick by Herman Melville

I read most of this book in 2014, but didn’t quite finish it. There’s no doubt Melville has an unparalleled skill with the English language. Strangely, I found all the characters, especially Ahab, comical, rather than frightening. Perhaps Ricardo Montalban’s performance in The Wrath of Khan has set the bar too high. A great read both as fiction and as a historical depiction of the times.

Talking with Tech Leads by Patrick Kua

Although not the case for a few years after college, these days I find myself more fascinated and interested in the challenges of growing and organizing people, rather than software or other technology. This book, with its many short investigations into the delicate balance the two inherent in the tech lead role, is a helpful resource. Each essay has a different author and so covers a wide range of viewpoints and situations. Far from being a deficit, the conclusion of this book – that the tech lead role is itself nearly undefinable and that there are no perfect solutions to efficiently lead groups of people working with software – is actually a valuable lesson.

career.fork()

Having just moved to Berlin and looking for work at the time, I felt compelled to investigate contracting and freelancing options, as many in Berlin do. Another short read, career.fork() touches on, but doesn’t attempt to completely cover, all the challenges one will face working for themselves. Like Tech Leads, this brevity is useful, as there aren’t any simple solutions to most of them. This admission is something I respect about both of these books, which was absent in another, Managing the Unmanagable, that I couldn’t finish years ago: it’s author seemed to have claimed the problem of working with developers solved.

Patterns of Enterprise Application Architecture by Martin Fowler

A classic architecture book from the 90s, today PEAA is not likely to be as practically useful as it once was, but is now almost a history book. The proliferation of powerful open source software frameworks means few people will need to use the techniques in this book. But it’s place as a foundational tome of knowledge on which many of those tools are based is obvious. The first architecture pattern it describes is familiar to anyone from the Rails world: active record.

Flatland by Edwin Abbott Abbott

A silly, short, enjoyable story that is as much a window into its times as it is a dive into mathematics and abstract thought.

The Little Tea Book by George Washington Hood

I don’t remember anything about this book.

Working Effectively with Unit Tests by Jay Fields

A great and focused book on unit tests. I find myself using and sharing ideas from this book all the time, and definitely recommend more developers read it.

From Eternity to Here by Sean Carroll

I bought this book perhaps 5 years ago, and nearly read through it. I’m glad to have decided to re-read and finish it. Mr. Carroll is a fantastic writer and scientists. This book covers issues deep enough to fill philosophy, as well as science texts, but is still easy to read.

The Orphan Master’s Son by Adam Johnson

A rather surreal fiction based in North Korea, I enjoyed and disliked this book for its ridiculously outlandish plot and characters. It was frustratingly unclear how much of this books ideas are based in actual facts about North Korea, and which were invented by the author, but none the less it has some fantastic sections that make it worthwhile.

The Girl With the Dragon Tattoo by Steig Larsson

In the past I’ve claimed to prefer non-fiction books to fiction, arguing history gives us enough fascinating stories that there is no need to invent our own. However after The Girl With the Dragon Tattoo I can no longer defend that position.

Fantastic characters, deep plot with incredible mystery, and scenes that make the suspense of any horror film feel mild make this one of the best books I’ve ever read. While it uses the real political and historical climate in Sweden to make the story even more riveting, it’s immediately clear where the fiction begins, unlike The Orphan Master’s Son.

My only complaint about this book is a practical one: at the time I read it, I had been travelling between the US and Europe frequently, and used reading as a way to get my sleep schedule back on track. Mr. Larson’s writing ruined those plans: unlike every other book, normally unconquerable exhaustion after international flights couldn’t stop me from staying up all night to finish it.

102 Minutes by Jim Dwyer

It would probably be insensitive to say I enjoyed this book, but whatever I felt, I couldn’t put this book down and finished in only a few days. Supported by what must have been a superhuman quantity of research, 102 Minutes covers every human emotion in detailing the heroism and tragedy of September 11th.

Refreshingly, 102 Minutes leaves no room for conspiracy theories, vilification of Muslims or Islam, or irrational fear of terrorists. In fact, it might be argued the book blames building codes more than anything for the tragedy: in a break from the minute-by-minute account of the morning of September 11th, the book details how building codes of the time were written to fit the design of the twin towers, rather than vice versa, and allowed for a construction that enabled the horrific collapse of the buildings.

The Island at the Center of the World by Russel Shorto

Second in my reading list after moving to New York City, this was a wonderful history on par with any other I’ve read. Despite a setting over 300 years in the past, I see the influence of the characters and events in this book everywhere I go in New York, which brings me great joy.

The Girl Who Played With Fire by Steig Larsson

The sequel to The Girl With the Dragon Tattoo contains the same spectacular writing and characters, so it’s still immensely enjoyable, but it’s more complex plot doesn’t surpass the first.

Aviation Weather by the FAA

Long ago, the FAA distributed information on weather phenomena and the technology used to predict and measure it together. It turns out weather itself doesn’t change, but our weather related tools sure do, so the topics were split into two books in the 70s. This book covers the former topic, and it hasn’t seen a republishing since 1975. All the information it contains is useful, but it could use with a bit of modernization still, if even just to show higher quality pictures of different types of clouds.

Starting Strength by Mark Rippetoe

A great and complete book on weight training. Rippetoe has a character that is unforgettable if not always PC or likable, but he seems to for the most part really know what he’s talking about. Why does he love milk so much though?

The Girl who Played With Fire by Steig Larsson

Following up on what is in some respects a cliffhanger ending, it’s inevitable that you will read this book to conclusion once you start on the second book in the trilogy. Despite Larsson’s continued excellent writing, I was happy to be done with this book: the story had gotten rather boring. I haven’t yet decided if I’ll read the fourth book.

The Martian by Andy Weir

Bookless before a short flight, I bought The Martian at an airport bookstore and finished it less than 12 hours later. I had already seen the film but it didn’t reduce my enjoyment of this funny and scientifically accurate story.

The movie and book are both excellent, but differ especially in theme. I’d love to discuss the details more with anyone who has enjoyed both.

Notably, I find that my consumption of potatoes has considerably increased since reading this book.

Other than a few simple rules, like drinking lots of water, most of what has helped has been a few simple items.

I’ve got all of them with me right now, since I’m writing this at the end of a trip from San Diego to Berlin, so I want to make a list while it’s easiest. Every traveller should have most or all of these at the ready for all their trips.

Eye Mask

This is one of the cheapest, but probably the most important single item for travelling. Without sleeping on a long flight, it’s simply not possible to be ready to go quickly once you arrive, and above all else your body uses light to decide when to sleep.

I used to try to put a blanket over my head, blocking out only some of the light but nearly drowning me in warm air, and I still see people do this. A good eye mask is still cheap, but blocks out more light than any blanket, and more than a cheap eye mask like the one you might be lucky to get on some airlines.

Noise Cancelling Headphones

Even the newest airplanes are loud. The engines are loud, the passengers are loud, the in-flight announcements are loud. A few minutes of this is ok, but after ten hours, loud noises cause fatigue as much as anything else.

Fortunately, in the last few years the amazing technology of noise cancelling headphones has emerged. These use advanced signal processing to actively reduce the loudness of ambient sound around you. They work best with consistent background noise, so they’re perfect for the endless drone of the engines.

They cost a bit more than even a good pair of over the ear headphones (which are good at insulating from sound, but don’t come close to active noise cancellation), but they’re worth it since you can use them every day.

Earplugs

Before noise cancelling headphones, earplugs were our best defense against noise, but they aren’t useless today. If nothing else, being able to switch between earplugs and headphones keeps either from getting too uncomfortable.

On the loudest flights, using both may be what’s required to get some peace.

Neck Pillow

For those of us who don’t get to fly business class, there aren’t many positions that really let us rest on a plane. My neck and my back are what get tired and uncomfortable the most. A neck pillow can at least help a little bit.

I have to admit I still haven’t found a really good one. All the ones I’ve tried, including my own, just don’t feel firm enough. I try any new ones I come across, and would be willing to pay for a good one, but so far the one I got at Target for $15 is the best.

Spare Contacts and Glasses

I can’t sleep in my contacts. My eyes quickly dry out, my contacts stick to my eyes, and its all no good. Fortunately I wear daily lenses, so throwing away a pair is no big deal. It took me way too long to realize it, but bringing spare contacts on the plane, in an easy to reach place, is a super simple way to make flying a lot more comfortable. Glasses help too if I’m not sure I want to put another pair of contacts in just yet.

Advil

I get headaches all the time. I get the worst headaches when I’m dehydrated. It’s really easy to get dehydrated on a plane. I almost always get really bad headaches when flying. So if I don’t bring something to help with my headaches, I’m pretty much miserable when flying.

I first started bringing Advil, but in my carry on bag that was not easy to get to during most of the flight. Now I just put some right in my small bag that’s always with me. Whenever I feel the need I can find some water and take some Advil. This mostly cures my headaches and makes flying so much better.

Food

I really can’t stand airline food. It’s not that healthy, not at all fresh, and tastes terrible. These days I generally plan on bringing enough food to keep myself alive for an entire day or so. That way there’s no chances of getting hungry and not being able to do anything about it, or eating bad food and feeling terrible after.

My go to flying food is simple stuff: bagels or other bread, some whole fruit (bananas are perfect because they’re already well packaged), and some sliced meats. Eating something fancy may seem nice, but usually I’m too tired to really enjoy eating anyway, and getting sick on a plane is no fun at all.

It’s taken me a few years to really settle on all these essentials, but now that I have I can generally handle anything that comes my way on even the longest flights. Now I just need to work on conquering the jet-lag that comes after.

When we left off after part 1, we had a server with a valid, signed certificate, but it was using the default Nginx configuration. This configuration is far from optimal.

At the end of this post we’ll have a secure HTTPS configuration on Nginx that scores an A+ rating on the SSL Labs report. We’ll even do a few extra tweaks that improve performance and user experience.

In addition to the descriptions and code snippets here, I’ve compiled a ready to go SSL configuration file for Nginx, a nearly ready to go example site configuration file, and a complete list of all the sources I used while researching for these articles, and posted them for anyone to use freely on Github.

Disable SSLv3

By default Nginx still enables SSLv3¹, which has been vulnerable to the POODLE attack since October 2014. The only browser that doesn’t support newer protocols out of the box is IE6, and even it can be configured to use TLSv1, so there’s no reason to support SSLv3 anymore.

SSL Labs rightly limits your server’s SSL score to C if SSLv3 is enabled, so this is the first thing to change.

1
2
3

# support only known-secure cryptographic protocols
# SSLv3 is broken by POODLE as of October 2014
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

Send the Entire Certificate Chain

Browsers use root certificates from Certificate Authorities to determine which server certificates (such as the one from your website) should be trusted, but there’s almost always an intermediate certificate. To be sure your server’s certificate is valid, browsers need to know about this intermediate certificate.

Of course, browsers can find and download these intermediate certificates, but this slows down the process of connecting to your website, and makes the whole process more complicated giving attackers more surface area to exploit.

It’s much better to simply configure Nginx to send this intermediate certificate along when users first connect. In fact, your SSL score is capped at a B if you don’t.

Your Certificate Authority probably provided you with links to download your intermediate certificate, so once you’ve found it, put it somewhere safe on your server, and tell Nginx about it like this, and then make a new file that concatenates your certificate and the intermediate certificate together. Then tell Nginx about that one like this²:

1
2

# send intermediate certificate during new sessions
ssl_trusted_certificate /etc/nginx/ssl/startssl/sub.class1.server.ca.pem;

Ciphersuite Configuration

The SSL/TLS protocols actually don’t provide any encryption by themselves. Instead, they simply allow a server and client to agree on and start communicating via a channel that could have one of any number of encryption schemes.

Your server and a client will use SSL/TLS to agree on a combination of four things: key exchange algorithm (how to safely share encryption keys between the server and client), authentication (to make sure only the intended sender/recipient are communicating), encryption algorithm (actually encoding the messages so no one else can read them), and message digest algorithm (to make sure the message was not tampered with or corrupted).

There are many of each of these algorithms, all with varying features, performance, cryptographic strength, and browser support. Many of the algorithms have known weaknesses that make them unsuitable for use today. Using the latest version of a browser is usually enough to protect an individual user but, unfortunately, a lot of older browsers have insecure defaults.

The goal of cipher suite configuration is to ensure compatibility with as many browsers as possible, without compromising security or, to a lesser extent, performance.

This will be done by setting a configuration string that OpenSSL understands in our Nginx configuration. To keep thing simple here’s the relevant configuration lines:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# make the server choose the best cipher instead of the browser
# Perfect Forward Secrecy(PFS) is frequently compromised without this
ssl_prefer_server_ciphers on;

# support only believed secure ciphersuites using the following priority:
# 1.) prefer PFS enabled ciphers
# 2.) prefer AES128 over AES256 for speed (AES128 has completely adequate security for now)
# 3.) Support DES3 for IE8 support
#
# disable the following ciphersuites completely
# 1.) null ciphers
# 2.) ciphers with low security
# 3.) fixed ECDH cipher (does not allow for PFS)
# 4.) known vulnerable cypers (MD5, RC4, etc)
# 5.) little-used ciphers (Camellia, Seed)
ssl_ciphers 'kEECDH+ECDSA+AES128 kEECDH+ECDSA+AES256 kEECDH+AES128 kEECDH+AES256 kEDH+AES128 kEDH+AES256 DES-CBC3-SHA +SHA !aNULL !eNULL !LOW !kECDH !DSS !MD5 !EXP !PSK !SRP !CAMELLIA !SEED';

Now I’ll explain the rationale that went into crafting it.

Make the server choose the ciphersuite

Many browsers, especially old ones, will make poor ciphersuite choices on their own. The first directive ensures your server will choose from the list of ciphersuites supported by both the browser and server.

Disable null and low security ciphersuites

Strangely, it’s possible for SSL/TLS to use no encryption if configured improperly. Fortunately it is easy to disable this. OpenSSL also has its own internal list of ciphersuites with known low security, and disabling those is a good starting point.

Disable insecure algorithms

Some algorithms have known or suspected vulnerabilities, and we can disable or limit their use where appropriate. The following algorithms in particular should be disabled:

MD5: completely broken, still common

The MD5 hashing algorithm is commonly used but has had known weaknesses since 1996, only 4 years after it was introduced. Today, MD5 is famously vulnerable to collisions, especially with GPUs. It simply isn’t safe to use any more.

RC4: former poster child, recently tarnished

The RC4 cypher is also commonly used, and until recently was widely recommended. However, information revealed by no less than Edward Snowden himself has suggested that it’s possible the NSA has the ability to break RC4.

Combined with research showing theoretical vulnerabilities in RC4, the possibility that there are working attacks against RC4 in the wild is too plausible to ignore. Microsoft has issued a security advisory to disable RC4, and the IETF is drafting a memo to require clients and servers never use RC4.

SHA1: rapidly approaching affordable attacks

In part 1 we generated a certificate request using SHA256 instead of SHA1. For the same reasons, we also have to disable ciphersuites that use SHA1 as the hashing algorithm. No attacks against SHA1 have succeeded as of today, as far as we know, but it probably won’t be long.

Disable little-used ciphers

These are not common, and disabling them just simplifies things and reduces the surface area for attacks³.

Support perfect forward secrecy whenever possible

Perfect forward secrecy allows a secure connection to use encryption keys that are custom generated for that specific session. The security advantage this provides is incredible: even if the private key for a server is compromised, none of the messages sent to that server in the past can be decoded.

Furthermore, even if an attacker manages to successfully compromise a session key used by your server, they only gain access to a single session. This increases the cost, and decreases the reward, of attacking communication with your server.

A great recent example of this is Heartbleed: with perfect forward secrecy, the Heartbleed vulnerability can only expose individual sessions. You’d still have to update your server’s private key, but almost all user data would be safe even if your private key were exposed.

Most reasonably modern browsers, with the notable exception of IE8, support key exchange algorithms with perfect forward secrecy.

There is one additional configuration change that needs to be made to keep PFS ciphersuites secure. By default Nginx will generate 1024-bit RSA keys for PFS ciphers, but that can be overridden. Use the configuration changes below and be sure to use openssl to generate the 2048 bit keys (it can take a few minutes).

1
2
3
4
5

# Use 2048 bit Diffie-Hellman RSA key parameters
# (otherwise Nginx defaults to 1024 bit, lowering the strength of encryption # when using PFS)
# Generated by OpenSSL with the following command:
# openssl dhparam -outform pem -out /etc/nginx/ssl/dhparam2048.pem 2048
ssl_dhparam /etc/nginx/ssl/dhparam2048.pem;

Optimize for performance where appropriate

Despite some algorithms occasionally being found vulnerable, modern browsers actually support a comprehensive suite of extremely powerful security tools. All four algorithms specified by NIST for Suite B cryptography , including AES and SHA2, are currently supported by a good portion of the browsers in use today.

Many security experts consider that using the longest key lengths currently supported does not have any measurable impact on security, and simply reduces performance⁴.

A common configuration that takes this into account is to support these most secure variants, but prefer more reasonable key lengths. For example, the configuration above supports both the ECDHE-ECDSA-AES256-SHA384 and ECDHE-ECDSA-AES128-SHA256 ciphersuites, but prefers the shorter key length variant. Both provide excellent security with no known attacks. This makes the default for most users secure and reasonably performant, but allows users to demand the most secure ciphersuites if they so desire.

Enable HSTS

Many concepts in security involve correctly implementing a specific, precise procedure like a cryptographic algorithm to achieve a mathematically proven level of security. HSTS is not one of them.

Enabling HSTS simply tells browsers not to make any plain text requests to a server ever again.

In theory, this provides no benefits over a server properly configured to require a valid HTTPS connection for all resources, at all times. In practice, HSTS protects against a huge number of configuration errors that are easy to make.

It’s also easy to implement: all that is required is for the server to send a valid HSTS header with each HTTP request, and the browser will do the rest.

1
2

# enable HSTS including subdomains
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains;'

This tells browsers to avoid plain HTTP requests to your server and all subdomains for one year. It’s perfectly reasonable to remove the includeSubdomains clause if not all your subdomains are ready for HTTPS.

Note that by enabling HSTS, you are essentially promising to browsers that your server will correctly respond to HTTPS requests until the header expires. This means its probably not something that should be enabled on day one of an HTTPS roll out.

Once you’re comfortably set up running HTTPS with no problems, you can also submit your site for HSTS Preload, allowing the latest versions of popular browsers to ship already knowing your server expects only HTTPS requests. This is incredible: modern browsers will never make even one HTTP request to your server.

The security benefits of HSTS are profound enough that SSL Labs requires it as the final prerequisite of an A+ SSL rating.

Improve Performance

Finally, there are a few more configuration changes that should be made to improve performance. As far as I know these either have no detrimental impact on security, or actually help improve it.

Set up OCSP Stapling

Before a browser will connect to a server using HTTPS, it has to check if the certificate the server is using is still valid. An upgrade or response to an attack could cause a certificate to be revoked, and its important to know about it.

Without further action on your part, every browser connecting to your server will have to pause when first connecting to ask an OCSP server for the latest revocation information for. OCSP stapling allows your server to do this ahead of time. The OCSP responses are signed by your Certification Authority, so browsers will be able to trust them, even if they come directly from your server.

This also cuts down on traffic to OCSP servers(a nice thing for you to do), and protects your server against unexpected interruptions because of downtime or denial of service attacks against your OCSP server.

1
2

# allow Nginx to send OCSP results during the connection process
ssl_stapling on;

Support SSL Session Caching

By far the biggest concern when moving to HTTPS is performance: both extra load on servers, and slower page load times on the user side. By large, the overhead for an established secure session is not significant anymore.

However, the process of initially connecting via HTTPS involves many more round trips between client and server than HTTP, so there is still definitely a noticeable impact on page load times.

With that in mind, it makes sense to cache SSL sessions for at least a few minutes, so that users only have to pay that cost once. Nginx is almost configured correctly out of the box to do this. The only change needed is setting a size limit for the session cache. The actual timeout is specified with ssl_session_timeout, which defaults to 5 minutes. The 10MB cache size limit is suggested by Nginx’s own HTTPS configuration guide:

1
2
3
4

# Cache SSL Sessions for up to 10 minutes
# This improves performance by avoiding the costly session negotiation process where possible
ssl_session_cache builtin:1000 shared:SSL:10m;
# ssl_session_timeout 5m; # this is a default, but can be changed

Resources and Thanks

I hope this guide can be considered comprehensive enough to be useful, but I would be lying if I said it was even close to covering everything. Security is a complicated, rapidly changing challenge. With that in mind I want to call out some of the best resources I’ve found both to provide more information and thank the authors of these great works.

• Eric Mill’s Switch to HTTPS Now, For Free, which first set me down this path
• SSL Lab’s SSL/TLS Deployment Best Practices - a really great and understandable deep dive
• Mozilla’s extremely complete Server Side TLS wiki page

1. The Nginx blog has an article about POODLE, suggesting that everyone using Nginx disable SSLv3, so hopefully the default will change soon. ⏎
2. Many tutorials, like Eric Mill’s Switch to HTTPS Now, For free suggest performing something equivalent by concatenating the root certificate, intermediate certificate, and your server’s certificate together into one file. This works just fine, but I prefer keeping the files separate for clarity. Use whichever method works better for you.

   I asked about this on the <a href="http://forum.nginx.org/read.php?2,256613,256621#msg-256621">Nginx mailing list</a>
   and it turns out this works, but only by accident, and may break in future
   versions of OpenSSL or Nginx at any time. Use the standard concatenation method.
   

   ⏎

3. Some of these ciphersuites are more common in a few contries, and if you’re serving traffic to primarily one of them, it may make sense for you to enable them. ⏎
4. For the same reasons, I don’t believe it makes sense to use certificates with 4096-bit keys, 4096-bit Diffie-Hellman key exhange parameters, or similar changes. You can actually improve subscores of your SSL score using them, but it will come at a performance cost. ⏎

Well, things are different now. Today we know it’s not a good idea for any web traffic to be unencrypted, and anyone running a website, no matter the content, should configure a strong HTTPS setup today.

Embarrassingly, my own website has not supported HTTPS at all for almost two years¹.

Eric Mill’s fantastic Switch to HTTPS Now, For Free finally gave me the kick in the pants I needed, and over the holidays I spent the time to set up HTTPS and tweak the configuration to achieve an A+ on the Qualys SSL Report.

It took a good amount of research, but I’ve settled on a close to optimal setup, and want to share how I’ve achieved it on Nginx. Besides the actual configuration, I’ve included explanations of what all the components of a secure setup do, and why it’s the best option.

This is part 1, where we’ll talk about basics and deal with setting up certificates.

Part 2 covers more Nginx configuration, especially ciphersuite setup.

Initial Setup: Use a Self-Signed Certificate

Simply enabling HTTPS requires very little: a server needs an encryption key and a certificate file. Both of these can be generated quickly and easily on any machine with OpenSSL installed.

While these self-signed certificates don’t provide any true security² its worth the time to set one up up before moving onto a real certificate to get a feel for the process and fix as many issues as possible early on.

There are far too many tutorials already on generating self-signed certs, so I won’t go into a huge amount of detail here. A simple command like the following will suffice:

1
2
3

mkdir /etc/nginx/ssl
cd /etc/nginx/ssl
openssl req -new -x509 -sha256 -newkey rsa:2048 -days 365 -nodes -out /etc/nginx/ssl/nginx.pem -keyout /etc/nginx/ssl/nginx.key

The Nginx configuration section for basic SSL³ is also straightforward. Just add the following configuration to your nginx file:

1
2
3
4
5
6
7
8
9
10

server {

      # [...]

      listen 443 ssl;
      ssl_certificate      /etc/nginx/ssl/nginx.pem;
      ssl_certificate_key  /etc/nginx/ssl/nginx.key;

      # [...]
}

(Both code snippets above adapted from the Linode certifficate guide, also linked above. It’s one of the best)

Now armed with a valid certificate, restarting Nginx should allow your website to load over HTTPS, although it will probably greet you with a nasty warning because the certificate is self-signed. It’s time to do a few initial checks for critical features before we dive in with a full certificate.

Check for a Modern Version of OpenSSL

The OpenSSL library is the almost ubiquitous SSL and TLS library, and its used by nearly every web server, including Nginx. If your version of OpenSSL is out of date, it might have one of any number of security vulnerabilities.

The worst of these is, of course, Heartbleed, which potentially allows leaking all sorts of data including your webservers private keys. Heartbleed was first made public in April 2014, but many websites are still vulnerable. Don’t be one of them.

Check the OpenSSL website for the latest stable version, and then check yours like this:

1
2

$ openssl version
OpenSSL 1.0.1k 8 Jan 2015

Ensure You’ve Created a 2048-bit, SHA256-signed Certificate

Self signed certificates can be easily regenerated with no cost or downtime, so its best to iron out certificate configuration issues now. Revoking even a free StartSSL certificate costs $25, so mistakes later on are more costly and time consuming.

The most important certificate configuration setting is the fingerprint hashing algorithm. Until recently, most certificates were signed using SHA1. However, Google, Microsoft, and security researchers in general are now pushing hard to deprecate SHA1 quickly: its becoming dangerously insecure as computing power advances. In its place, new certificates should be signed using SHA256.

There are no known attacks against SHA1 yet, but both Chrome and Firefox will soon show warnings or errors for certificates signed with SHA1, so creating a new certificate today without using SHA256 is a big mistake.

Likewise, a 2048-bit RSA key size is currently optimal⁴. 1024-bit certificates are well into the realm where someone with a sufficiently powerful computer network could break them. Again, browsers are now actively discouraging their use: Mozilla has removed 1024-bit Certificate Authority keys from the list of trusted certificates starting in Firefox 32, released in September 2014.

If you used the commands above to generate your self-signed certificate, it should already use SHA256 and a 2048 bit RSA key, but the following commands can be used to check:

1
2
3
4
5

openssl x509 -in /etc/nginx/ssl/nginx.pem -text -noout | grep "Signature\|Public-Key"
# Should give the following output:
# Signature Algorithm: sha256WithRSAEncryption
# Public-Key: (2048 bit)
# Signature Algorithm: sha256WithRSAEncryption

(Adapted from this ServerFault Answer)

If it shows sha1WithRSAEncryption or (1024 bit) instead, go back and regenerate your certificate with the correct settings.

Check for Mixed-Content Warnings

At this point, there’s a very good chance some resources on your website, like Javascript, CSS, or images, are still being loaded over HTTP, even when the initial request is made over HTTPS.

An example of a mixed-content warning in Firefox

It used to be considered enough to use HTTPS only for critical sections of a website, such as a login page and form submissions, but no longer. Modern browsers block the more dangerous varieties of mixed contact (namely Javascript and CSS files).

This has a tremendous security benefit to users, because those files can potentially be modified while in transit and cause serious harm: sensitive user information can be stolen, or malware added to their system.

Fixing mixed-content warnings is very specific to your website’s code, but in principal it simply involves changing any links that start with http:// to https://. This includes links to any resources loaded from other servers. If those servers don’t support HTTPS yet, you have to get rid of the resource entirely or host it yourself, if possible.

If you really need to support both HTTP and HTTPS, protocol-relative URLs can help, but are discouraged.

Doing it For Real: Use a CA-signed Certificate

Now that these basic issues are tackled, it’s time to create a certificate that browsers will recognise as trusted. This can be a lengthy process for a couple of reasons, so let’s cover the prerequisites first. You’ll need:

1. An account with a Certificate Authority.
2. Access to webmaster@yourdomain.com, postmaster@yourdomain.com or whichever email is listed in the SOA record of your domain’s DNS entry.
3. A certificate request(CSR) file.

Step 1 is potentially a little more cumbersome than signing up for an average website, which is understandable considering the security concerns, but should be manageable. If you haven’t chosen a certificate authority, StartSSL is excellent, and free. Paid options include Verisign and Comodo. Please don’t use GoDaddy.

Step 2 won’t be covered here in detail as it’s highly specific to your DNS setup. If you don’t already have this set up properly, it can take a few hours for the DNS entries to take effect once you’ve made the change, so get started now.

However, if, like me, you are using Fastmail for email from your domain, then they have already set up everything for you. If you aren’t using Fastmail, they are awesome and I can’t recommend them enough.

Once you’ve completed steps 1 and 2, you can create the CSR. This file details what domain you want a certificate for, and any options. Some Certificate Authorities will offer to “help” you by generating a private key and CSR for you in the browser. Decline their offer, since we’ve already generated a private key, and we don’t need that potential breach of security.

The following command will generate a nice CSR for you:

1

openssl req -new -sha256 -key /etc/nginx/ssl/nginx.key -out /etc/nginx/ssl/yourwebsite.com.csr

Paste that into the form for the CSR on your CA’s webpage, and they will send back a certificate. Keep it safe and store it on your server, somewhere like /etc/nginx/ssl/yourwebsite.com.crt.

If you happen to be using StartSSL, Erik Mill’s tutorial which I linked to above walks through every step perfectly!

Initially, you can simply point Nginx at the new key and crt file from your CA just like you did your self-signed cert and things should work⁵. Congratulations! Your web server is now running TLS with a valid certificate.

If you were to run the SSL Labs test on your website right now, you’d probably see something like this:

It’s not bad, but the default Nginx settings only get you to a C grade - barely passing. In the next part we’ll look at what it takes to configure Nginx so that you achieve an A+ rating. Stay tuned!

1. My server didn’t even respond to HTTPS, or anything on port 443, for this entire time! ⏎
2. For truly secure communication, three things are needed: verification the message came from who you thought it did (authentication), obfuscation of the message contents so that no one but the intended recipient can read the message (encryption), and a way to verify that the message was not changed while in transit (message digest). A self-signed certificate doesn’t provide any authentication, so it’s mostly useless.

   The Wikipedia page on TLS provides an excellent overview of how this all works. ⏎

3. When I say SSL, I really mean TLS. Both SSL and TLS share the same heritage. TLS is simply the name for newer versions. All versions of SSL are now out of date, but the name has stuck. ⏎
4. 4096 bit keys are, at this point, considered excessive except for Certificate Authorities, so 2048 is the best size. Remember, a 2048 bit key is not twice as secure as a 1024 bit key, it’s 2¹⁰²⁴ times as secure! It is twice as slow however. 2048 bits is going to be enough for quite some time, so 4096 bit keys just make the encryption process slower. ⏎
5. Initially, you will probably get an OCSP error (looks like this). This will go away in a few hours. The Online Certificate Status Protocol (OCSP) is a system for determining if a certificate has been revoked. Since your certificate is brand new, there’s no information in the system confirming your certificate is still valid, and it will take a little while to get there. We’ll learn more about OCSP in the next post. ⏎

Sharing the joy and power of building software with more people is perhaps one of the most significant challenges in the world right now, so I’ve tried to learn as much as possible about how to do it.

While I by no means consider myself an expert, I want to share some of what I’ve learned so far.

Praise Often, and Remind Learners that Getting Stuck is Normal

This is the most basic and core concept I’ve learned about teaching.

Remember that almost every student comes into the classroom worried, if not convinced, that they simply don’t have whatever mental faculties or background it takes to program. The world is full of voices that have told them this. Unfortunately, many of these voices come from within the software community.

Moreover, however much we programmers debate between ourselves if coding is more like math or writing, most students are terrified of anything that possibly has a mathematical foundation.

Women, kids, older people (according to Silicon Valley logic, anyone past 25 is probably considered “old”), and minorities are usually especially worried¹, but you’d also be surprised how much fear a few lines of Ruby can impart on young, well educated white guys.

Programming is hard and the fear of failing and looking dumb is something everyone struggles with. As a teacher our job is to combat that.

So far, my go-to tactics are:

1. strongly asserting that every programmer, no matter how experienced, struggles when learning. There aren’t certain people born with an ability to pick up programming without making any mistakes.
2. reminding students that they are capable of learning to code, and that the satisfaction that comes after struggling through something and finally prevailing is really enjoyable.

It’s not enough to simply state these things, they have to be proven through actual actions in the classroom. The first is easier: don’t be afraid to admit what you, even as a teacher, don’t know. Anyone who has taught knows that there’s no better way to secure a solid understanding of something than to teach it to someone else. As your understanding grows, be sure to share it with your students.

I don’t think there’s any shortcut for the second: nothing but actually getting the student to accomplish something that challenged them will do. Any coding curriculum should focus on quickly getting a new student to successfully build something, by themselves, to set a mood that encourages them. This is hard, but easier than ever today: we can write a few lines of Javascript and have our students create pretty pictures quickly. It might have taken weeks of painstaking work learning advanced C++ and OpenGL to do the same thing a few years ago!

It’s not completely clear to me where to draw the line when reminding students that getting stuck and making mistakes is normal. Sometimes I’ve taken a rather cynical route and said things like “our puny human brains simply aren’t very good at writing bug-free code, so we have to do what we can to keep our code simple, and we’ll still make mistakes all the time”. Some students probably appreciate brutal honesty and dark humor, others might appreciate a lighter touch.

Teach by Asking Lots of Questions, Carefully

No less a teacher (and learner!) than Socrates ensured that asking questions will always be core to every teacher’s tool belt², but there’s some nuance here that is extremely important to remember to keep it from backfiring.

Remember that every student is almost completely convinced they aren’t cut out for programming. If you’re particularly lucky (or good!), they are having a good time so far and have made something cool already. Still, most new students are probably one frustrating moment of giving up forever.

The reason why asking questions works so great for teaching is that in the process of coming up with an answer (any answer, not even a correct one!), forces students to think hard about something, and that’s how you learn. A talented mentor can ask questions that guide a student towards understanding without actually telling them anything³.

But being asked questions on the border of your knowledge is extremely taxing, and sometimes students just don’t come up with a good answer. Sometimes the question is bad, sometimes the question wasn’t properly matched with where they are in the learning process, and sometimes they just need the question phrased differently.

Not being able to answer a question can be pretty demoralizing, but there are ways you as a coach can make it worse! There are two pitfalls: asking “obvious” questions, and trick questions.

“Obvious questions” are useful, but dangerous. One way they often come about is when walking through some code, mentally performing each operation in turn. As we try to remind new coders, most math in programming is nothing more complex than basic arithmetic. For example, a teacher and student might have this exchange when going over a basic for loop:

“OK, we set i to zero. Next we add one. Zero plus one is?”

“One”

“Then we do [whatever is in the loop]. Then we start over: what was i?”

“One”

“Good, next we add one to i. One plus one is?…”

“Two”

If the student is with you, and knows what the result will be, everything is great. But sometimes all the chaos of learning is overloading their brain for the moment. They’re trying to answer, but they just can’t right now. Students can usually tell from the tone of your voice you expect them to know the answer, and when they can’t it’s really demoralizing. Be careful.

Trick questions are also something I try to avoid. It’s far too easy to demoralize your student by making them think you’re showing off.

Really, avoiding the pitfalls of asking questions just comes down to doing everything it takes to ensure to your student is sure you’re there to help them learn, rather than to make them feel bad, or to show off your skills. Create that environment, and then use questions wisely!

Don’t be Afraid to Review the Basics

A standard first day of coding ever usually looks something like this:

1. type some extremely simple expressions into a REPL
2. type almost identical expressions into a REPL, but assign them to named variables
3. fool around with strings and classes (maybe)
4. learn simple functions and loops
5. do Cool Things™ with all that knowledge

To keep students from becoming bored, there’s often a big push to move through the basics quickly. It’s much more exciting to actually build something cool, and you generally can’t do that with just expressions in a REPL, so this approach is reasonable.

But typing a few lines is not enough to learn any programming concept, and in some ways the foundational programming concepts are the hardest to truly grok.

What I often see is students go through the quick intro to variables, or functions, or loops, and because the examples are so simple, they feel mostly comfortable and move on. Then, when trying to build something more complicated, they get stuck not because of the new material, but because they are reaching the limits of what they’ve learned previously.

Most coding tutorials are written assuming students know all about variables by the time they get to for loops or functions, but that simply isn’t the case.

Don’t be afraid to go back a step or two when needed. A coach is absolutely critical for this, because experience allows the coach to figure out which core skill is lacking, and figure out how to fix it. Sometimes the student’s current exercise can be adapted, even if it’s for something more advanced, sometimes a simple example needs to be created on the spot.

In addition, there are some nuances to basic programming that I’ve discovered students have trouble with. They aren’t generally given entire chapters in a curriculum like variables and functions might, so they don’t get much coverage. I’ve found it takes a decent amount of time to explain these areas.

The first is scope. Christina Cacioppo’s Learning Online calls out variable scope as one of the most challenging basic concepts for students to learn, and my experience agrees. This is understandable, because every language has different, complicated, and sometimes unexpected (yes I’m looking at you Javascript!) rules for it.

At least for function scope, I’ve found something that works reasonably well: temporarily rearrange the students source code so that only the function they wrote, OR the code they wrote that calls it, but not both, can be seen on the screen at once (the low tech solution is to just insert a bunch of newlines). Then, we can reason about each bit of code independently.

Around this time students often get confused by function arguments and local variables passed to those functions that share the same name. I would love to hear peoples thoughts on whether these names should be changed to be unique, or kept the same.

In any case, when students can’t see both functions on their screen, they usually seem to be able to skirt around this area. I do know its helpful to remind students that calling functions they themselves have written is no different than calling other functions, which they’ve no doubt already done.

Another tricky concept is control flow during loops. It usually takes students a while to be able to calculate in their head what values a variable will take during each iteration of a loop, for example. Perhaps it’s the fact that a line like i = i + 1; looks much like an algebraic formula, but of course isn’t valid, or maybe it’s the idea of the same line of code executing multiple times with a variable having a different value each time that’s confusing⁴.

Teach by Modifying Existing Code

Most of the time, students start with little or no code, and build up something bigger, but this isn’t the only way to learn.

I like to take some existing code, especially code the students have written, and suggest changes to it. The key is to have the student make the changes, and before they run the new code, ask them what they think will happen. It’s OK if they don’t know, but they have to give it a good thought at least.

This works best once students are working with code with a little bit of complexity. Loops (especially nested loops), provide lots of parameters to tweak that can provide interesting learning opportunities.

My favorite path goes something like this: Start with a simple for loop (a more advanced exercise nests two):

1
2
3

for (var i = 0; i < 10; i += 1) {
...
}

1. Ask the student to double the termination condition from 10 to 20. Students usually get that this will make the loop do more of whatever it was doing before.

2. Change the start condition to something negative, say -5. Most students are initially perplexed but realize why it works fairly quickly once they see the output

3. Change everything else back, and then change the iteration from i += 1 to i += 2. Interestingly in my experience, students usually realize that the loop will now “skip” every other iteration, but don’t know, or don’t mention, that the loop will also only run half as many times. With a little more work, when they figure it out, it’s usually a pretty big moment of understanding that feels good for the student.

Do Not Enforce Your Professional Coding Standards

As an experienced developer, you’ve gotten to where you are by being pretty tough on yourself. You have strict standards for the quality of your code or your team’s code, and are more than willing to call teammates out to make the code more maintainable in the long term. On a professional team, this is a good thing.

When working with brand new programmers, it’s a great way to demoralize. The place where this is seen the most is in indentation, whitespace, and general code formatting. While you’ve probably formed strong opinions on exactly how code should be formatted, new programmers have no such concerns. It isn’t even on their radar. When you’re just figuring out how variables work, coming up with a good variable name isn’t something you can even begin to deal with.

Your job as a mentor is to ignore whatever horrors of coding style your students produce. I’m willing to claim that there is no code a first-day student can write that you can’t read well enough to coach them just fine.

At all costs, don’t express any disgust at your student’s code. Even something like “well, before I can help you, we have to fix your whitespace”, is enough to make someone feel really bad. I personally don’t bother pointing out most coding style issues to beginners.

If you really want to, you can do it, but only when your student is at a point where they’ve just had success solving a problem and are feeling good. Then very gently suggest syntax improvements. Something like “okay, now that you’ve got that working, lets make a quick change so that your code is easier to work with later”.

New students aren’t generally concerned with the “beauty” or “elegance” of their code⁵, so motivating them with those sorts of concerns probably won’t work. However, students generally ARE receptive to the idea of simplifying code, and offering ways to make their job easier later is often much appreciated.

Kids are the Ultimate Challenge

I’ve had the opportunity to help mentor younger kids (below age 12 or so) just a few times, and it’s been a blast: a tiring and intense blast.

In my (limited) experience, the challenges are not fundamentally different than those for adults, but the magnitude of the challenge, and the amount of leeway you have in solving those challenges are vastly different.

Like adults, kids are apprehensive about their abilities, and just as worried about failing. What makes kids different when learning to code is, I think, what primarily makes kids different from adults in anything else: kids aren’t good at managing their emotions, and kids aren’t as able to delay gratification. Let me give some examples:

• With an adult programmer, seeing a more advanced student’s work isn’t discouraging, because they understand that they will be able to build more impressive things over time. Kids see someone next to them doing something cooler than they’re doing, and are often immediately unhappy. Even if they do get a little jealous, adults won’t tell you. Kids definitely will make it known!

• Adults are able to push themselves all afternoon to learn something. They’ve experienced enough times when hard work paid off. Kids, when mentally exhausted, will make it painfully obvious. “Lets play an easier game”, a kid once said to me after about 3 hours of working with Scratch.

• Similarly, adults are more receptive to spending time on “boring” building blocks, like variables and functions, before building something “cool”. I think the only effective way to teach kids is to make the entire process as fun as any game, and that’s just plain hard with some of the basics. This is a hard problem to solve. Actually, it would make it much easier to teach adults too, but it’s more critical for teaching kids.

• In general, adults have more determination to code. Adults know their time spent learning to program might have huge professional or financial upside later. They’re willing to put in a little work. Kids on the other hand, aren’t motivated by such things: learning to code has to be a game, and if the game isn’t fun for even a short while, it’s hard to press on.

Does Show And Tell Help or Harm?

Here’s something interesting I’ve been thinking about: a lot of events for kids have a big demo at the end where all the kids get up on some sort of stage in front of everyone and show off what they’ve built. I can see how this can be really helpful: telling kids their work is worth showing off, and giving them an opportunity to do so, sounds like a positive thing.

But like I said, when kids see the work of a more advanced student, it’s really easy for them to get demoralized. The problem with these demos is that they often mix kids of vastly different ages and skills.

When a 7 year old shows off his or her extremely basic thing that he spent all day struggling through, and then a 12 year old shows off this complex thing, is the 7 year old really going to feel good?

I think the answer is more often than not, unfortunately, no. I can’t help but thinking that show and tell is mostly for parents to feel good, and that the effect they can have on a young students morale can be serious. Maybe demos should only be allowed when the age and experience level of all the students are similar.

Scratch

One last thought, I want to talk about Scratch for a second. Overall, I think Scratch is amazing for teaching kids. It makes it quick and easy to add really powerful visuals to programming, and doesn’t involve typing, which is actually a big deal for younger kids. The iPad app is flat out fantastic and easy to get started with as well.

However, I wish it came with more built in features that were higher level. For those that aren’t familiar, Scratch basically has you click and drag various blocks that more or less map to programming primitives, like if statements, variables, for loops, etc.

These primitives can be used to build anything, but it would be nice if it came with more powerful blocks, even if they didn’t correspond to programming primitives, so that at least some aspects of programming could be taught while keeping things fun for kids. It would be especially cool if, when the student is ready, these higher level blocks could be inspected and the actual primitives underlying them could be seen. Scratch does allow you to define your own blocks, so maybe someone has done this, and if so I’d love to hear about it.

Onward

For anyone looking to start coaching without a lot of experience, I can’t recommend enough that you do it! You won’t be a perfect coach immediately, but as long as you are willing to commit to genuinely wanting your student to succeed, you’ll get better.

It’s a completely new set of challenges for those of us used to writing code ourselves, but it’s something every software developer should practice.

Before long, when you’ve mastered the art of not touching the keyboard, you’ll know you’ve gained a valuable skill. Better yet, you’ll have helped excite and encourage a bunch of new software developers!

Thanks to Charlotte Chang and Joanne Daudier for reviewing this post

1. Without a doubt, coaching events targeting specific groups like BlackGirlsCode, RailsBridge, RailsGirls, etc. are an enormous help and are absolutely necessary. I’d encourage anyone to volunteer at these events: it’s an eye opening experience for those of us who got here without the explicit discouragement many groups of people face. ⏎
2. In fact there’s a great term for this form of teaching: scaffolding. ⏎
3. Its probably not a good idea as a coach to only ask questions, but they’re a great start, and knowing what extra bits of clarifying information to add when a student has figured out something on their own can really help. Adding too much information can hurt as well, so it’s a balancing act like many things. ⏎
4. A lot of people will probably say the solution is to teach functional programming, all variables should be immutable, and all functions pure. I think this might actually be helpful, at least in some cases. Students definitely are comfortable with the idea of a function that takes some inputs and just does something with them. Functions or methods that maintain their own state often perplex them. ⏎
5. According to Charlotte Chang, who recently went through a developer bootcamp program, many developers quickly do become very focused on code aesthetics, so if you’re coaching more experienced students, this may not be the case. And if you are coaching very new students: enjoy it while it lasts! ⏎

I wrote my response assuming that the author of Why Women Shouldn’t Code was just another “old white dude” telling women what to do. Embarrassingly, I discovered that in fact the author was a woman! Here I was, trying to write some words supporting gender equality, and I made the classic mistake of assuming everyone on the internet is a man. Oops.

It’s often said that no-one thinks they are part of the problem of sexism, and this was a good reminder that it really takes a lot of work to over come biases that are common in society. I’ll try to do better next time.

After all this I was really wondering if I should even publish anything about the original article. The internet is already full of men telling women what to do or think. Finally I decided that it is worth speaking up about, if nothing else because I want to make it clear, on my own blog, what my own opinions are. But also, Why Women Shouldn’t Code has some seriously wrong assumptions about the nature of coding, something I hold very near and dear. So let’s talk.

On the Innate Differences Between Men and Women

Sure, you don’t need to do a brain scan to discover there are biological differences between men and women.

But taking the leap from “the part of the brain that we think is somewhat responsible for extremely high level activity X is slightly bigger in men, on average” to “thing X should only be done by men” is simply not a viable line of thought.

Proving differences in aptitude of any high level skill is almost impossible to support with science. There is way too much complexity in the human experience to ever come to a meaningful conclusion.

Besides, we can’t even measure the differences in productivity between teams of software developers even if we try to make the composition of the team as identical as possible. Given the same requirements, different groups of developers won’t even build the same thing. One team wouldn’t even build the same thing given a second chance.

Part of what makes creating software hard is that we don’t conclusively know what makes a team good or bad at it, even though we’ve been doing it for at least 70 years¹. Under those conditions, is it really wise to exclude 50% of the population from contributing?

Most importantly, even if we did some day conclusively prove that on average the biology of a woman makes her less adept at writing code, who cares? Men do things that women are supposedly better at all the time, and no one bats an eye. Let them code.

On the Definition of the Profession of “coding”

If a software job simply consists of writing a program to do exactly what someone else tells you it should do, then there’s no question why women don’t want that job: that job sucks. No one wants that job.

Fortunately, while probably more common than we’d like, that job isn’t something that’s really needed. What we do need are people who can not only write good code, but talk to other people who are experts in other things, and together build something that is both useful and possible to build in a reasonable amount of time, for a reasonable cost. This job is hard, it requires technical AND people skills, and many people find it extremely enjoyable.

By the way, you don’t even have to code as part of a job. Coding can simply be done for fun, on your own, or with some friends, or even random strangers from the internet.

Even after robots have taken over the world and humans just sit back on their space cruise ships, someone will surely still be writing code for fun (probably even code that a million other people have already written). No one needs to tell you what to code, and you don’t even need to ask permission. That’s why it’s awesome. It’s the pure joy of creation².

On 16 “Data Points” Being Enough to Prove Something

When you go to a toy store, the boys section is filled with superheroes, trucks, trains and airplanes. The girls section is filled with dolls and fake kitchens. Do we make fake kitchen toys for girls because that’s what they like, or is that what they like because that’s what we make them?

These sort of questions of causation have confounded humanity for so long that the entire idea of science was created to help answer them. While still lacking, there are a number of tools that we have today to help. Sample sizes should be large, biases in selecting the samples should be taken into account, and the study itself should be administered as a double-blind trial, all to make sure we aren’t tricking ourselves.

What definitely ISN’T in that toolkit is cherry-picking a handful of stories from people who’s lives we personally have had a long and significant influence over, and using those stories to support a belief we’ve had since before those people existed.

1. For a great collection of mostly sound scientific research into what we DO know about reading software, watch Greg Wilson’s fantastic talk What We Actually Know About About Software Development, and Why We Believe It’s True, and then read the resulting book: Making Software: What Really Works, and Why We Believe It. ⏎
2. You could even say the joy of nurturing something. ⏎

Digital Apollo: Human and Machine in Spaceflight by David Mindel

According to Goodreads, I actually finished this book on December 31st, 2013. But I’m putting it here because I easily re-read it twice in 2014: I based much of my talk from Mountain West Ruby and RailsConf on content from the book. Digital Apollo does an excellent job of covering development of hardware and software during the Apollo Program, and really all the projects leading up to it. There are technical sections, but they aren’t overly in depth and the main narrative isn’t dependent on understanding every detail.

The Adventures of Sherlock Holmes by Sir Arthur Conan Doyle

I have to credit Star Trek: The Next Generation for really making me aware of these excellent stories years ago, and while I’ve read a few here and there, it was only this year when I sat down and finished this 12 story collection. They’re amazing bits of writing, and hugely refreshing from non-fiction, which is what I generally read the most. Some of the plots that must have been original when these stories were published seem cliché today, but surely they didn’t when first published.

Failure Is Not An Option by Gene Kranz

Far more than an interesting story about the space program, this is a great read for anyone who has ever wanted to accomplish something extremely challenging that no one has done before. Kranz does an incredible job of describing the details not just of all the technical challenges and accomplishments of manned space flight, but of the emotions and team dynamics as well. Anyone doubting that any person can, with the right amount of determination and teamwork, accomplish anything should read this book.

The Path Between the Seas by David McCulloug

I’ve been reading this book on and off for almost two years (I started in early 2013). It’s truly a monstrosity, covering the building of the Panama Canal in incredible, but interesting detail. To be honest, I found the first half of the book, which details the comically failure-ridden initial efforts by the French, much more entertaining and useful. The second half, where the Americans basically come in, fix all the problems, and triumph, is great for national pride, but there’s not as much to learn from it.

The Day the World Discovered the Sun by Mark Anderson

Astronomy and history are both long time interests of mine, but I found this book mediocre at best. It covered too many characters, interweaving their stories in a way that was hard to follow, and the writing felt like it was trying to be too “grand”. Still, it’s a short book, and describes a very interesting and dramatic series of scientific endeavours spanning the entire globe, so I can’t say I didn’t enjoy it a little.

Javascript: The Good Parts by Douglas Crockford

I re-read this book after working more deeply with Javascript this year than ever before. Having considerably improved with the language and many of its core concepts, I found the re-read so valuable I wrote up an entire review.

How to Win Friends and Influence People by Dale Carnegie

In some senses, everything in this book is obvious and self-evident to anyone who has ever had feelings. On the other hand, the writing style is quite enjoyable and it’s at least a great reminder of how to work with others. For most of us, is probably a deeper exploration into describing what makes humans happy and angry than we’ve thought about before. If you’re turned off by the social-engineering-sounding title, one of my friends proposed a more accurate, alternate title: How to Be Friendly and Be an Influencer.

The Guns of August by Barbara Tuchman

While I found it hard to follow at times, there can be no doubt after a chapter or two why this book won a Pulitzer: the depth of research and fantastic writing style make this book practically a work of art. I was pretty tired of epic history books after reading The Path Between the Seas this year, and Embers of War last year, but still had to finish this book once I started. While both have similar themes, I preferred Embers of War.

All the Shah’s Men by Stephen Kinzer

After The Guns of August, the straightforward but extremely captivating writing style of this book was refreshing, and I finished it in just a day or two. Anyone looking for a lens into the cultures of the middle east would benefit from reading this short but exciting book.

One Minute to Midnight by Michael Dobbs

Yet another captivating history, this time on the Cuban missile crisis. Unlike The Day the World Discovered the Sun this book is not hard to follow despite covering dozens of events all over the globe happening just minutes apart. As yet another book documenting the folly of war, this time because of the inability of even leaders like Kennedy and Khrushchev to control their own forces enough to avoid terrible outcomes, I’ve pretty much got that genre covered for a while. Fortunately, next on my reading list is Moby Dick: a complete departure the trend. I didn’t quite finish it in 2014 though.

Whenever you have a loop that is modifying a variable in each iteration of the loop, consider a functional programming approach. It will usually result in less code setting up and returning variables, which makes the code that actually does the interesting stuff stand out more.

Any time you are taking every element of an array and want to produce another array with modified variables, you can use map. And any time you have an array and want to use each value in the array to construct a single result at the end, you want reduce.

To explain the difference, from a more common, imperative approach, let’s imagine you have a short array of integers, and you want to create a new array with all those integers incremented by one. You might do it like this:

1
2
3
4
5
6
7
8

def add_one_to_array(old_array)
  new_array = []

  old_array.each do |element|
    new_array<< element+1
  end
  new_array
end

That will work just fine. And because you’ve probably written tons of loops just like that one, it feels intuitive. But I would argue you can make the code much clearer, while doing the same thing, and reducing the chance of bugs sneaking in. Here’s how:

1
2
3
4
5

def add_one_to_array(old_array)
  old_array.map do |element|
    element + 1
  end
end

When you call .each on an Enumerable (the module that handles all sorts of stuff regarding working with arrays and other collections), all .each does is execute whatever is in the block (everything inside the do…end in each method is a block). Thats why the code in the first example has to actually do the heavy lifting of pushing data into the new_array variable.

The .map method on Enumerable does a bit more for you: it uses the return value of the block you pass to it, and collects all the return values from running the block with each element, turning that into a new array. You don’t have to bother creating a variable and assigning it into an empty array, explicitly updating the array, or even returning the array. The return value of .map is the array that results.

It also tells everyone reading the code something very important: the code that follows takes some code and uses it to transform one array into another. With .each, it could do anything, so you have to carefully read the code to ensure it doesn’t do something weird.

There’s a whole bunch of helpful methods defined on Enumerable, and the docs are quite helpful. They all do different things, but the idea is similar: they all work on a collection of some sort, and each one can be thought of as a single, specialized, powerful tool. Go read through the documentation and fool around with a couple.

The best part about is all this functionality is available across many languages. After a while, you’ll be able to jump into countless languages: Scala, Javascript, Haskell, and of course all the Lisps share these ideas, even if the details or names differ.

Rather than simply learning the quirks of a Ruby library, you’re learning a vocabulary and toolset that all functional programming languages share!

Of course, there’s always more to learn, and there were more than a few very experienced Ruby programmers that learned about a new operator last week: the flip-flop.

Nithin’s blog post gives a great overview of the syntax, so lets look at a more complicated example from Reddit:

1
2
3
4
5
6

a=b=c=(1..100).each do |num|
  print num, ?\r,
    ("Fizz" unless (a = !a) .. (a = !a)),
    ("Buzz" unless (b = !b) ... !((c = !c) .. (c = !c))),
    ?\n
end

This code clearly came from an obfuscation contest¹, and I’m not even going to attempt to suggest that I understood how this code worked after first reading it. But I was intrigued. Never mind the flip-flop operator, most of this code looks unfamiliar to someone used to reading idiomatic Ruby, and I wanted to know how it all worked. So lets break it down piece by piece, and see if some sense can be made.

Starting out with some assignment

The first line is perhaps the most normal. Chaining assignment is used frequently in many languages. And while many of the methods we use in Enumerable, like map, return something useful, the each method is actually defined on the Range class, and just returns the range.

But the code above uses the a, b, and c variables before the each iterator finishes, what is their value then? Let’s run a simple test script to find out:

1
2
3
4
5

# a no-op each
a = (1..2).each do |num|
  puts a.inspect # => nil
end
puts a.inspect # => (1..2)

Aha, it just is set to nil. Of course a variable that isn’t first initialized will throw an error, so this first line is really just a short way of initializing the a, b and c variables to something, before the start of the iterator. Let’s do out first refactor of the code then, to make it more readable:

1
2
3
4
5
6
7

a = b = c = nil
(1..100).each do |num|
  print num, ?\r,
    ("Fizz" unless (a = !a) .. (a = !a)),
    ("Buzz" unless (b = !b) ... !((c = !c) .. (c = !c))),
    ?\n
end

This code works the same way, so we know it was really a refactoring, with no changes to the behavior of the code.

Fun with Printing

The next line is actually the entire body of the block passed to each: the print method takes multiple arguments, and notably, does not automatically print a newline at the end (puts on the other hand, does always print a newline).

But what in the world does ?\r do? It turns out to be a poorly-documented character literal. It’s one character shorter than creating a string, such as "\r", but with the same result.

And what is "\r" anyway? It’s a carriage return, the little known sibling of the newline. Even in the 21st century, our computer screens still basically behave like a typewriter. Advancing to the next line and moving the cursor to the start of the line are two distinct actions, and so they have distinct character codes. Of course, the fact that Windows requires both a carriage return and a newline character, whereas Linux and OS X systems assume a carriage return with just a newline², creates more than a little confusion.

So, in any case, what sort of behavior can a carriage return character give us? Let’s run a few experiments:

1
2
3

print "hello", " ",  "world", "\n" # => hello world
print "hello", "\r", "world", "\n" # => world
print "hello", "\r", nil    , "\n" # => hello

How interesting! A carriage return lets us write some text, and then later while writing the same line, essentially decide to erase that text. Remembering the requirements of the Fizz Buzz problem, and how one must ONLY print a number when neither Fizz nor Buzz are printed, the utility of this behavior is obvious.

Finally, flip-flop

At this point we can easily describe the overall structure of the code: it loops through the numbers 1 to 100, using control characters to optimistically print the number, and then based on the logic of flip-flops, print Fizz and/or Buzz instead of the number when appropriate. But when is the “appropriate” time to print Fizz or Buzz? And how does a flip-flop and only three temporary variables achieve that? Lets take a look at just the first use of the flip-flop, on line 3 of the original code.

The first thing to note is that the conditions of the flip-flop operator are actually assignment. This took me a long while to spot, and indeed is a common source of bugs. In this case though, it’s not a bug, its a feature.

The flip-flop operator is going to evaluate the “truthiness” of whatever expression is inside it, and remembering that the assignment operator in many languages returns a value, we can figure out what the flip-flop operator will do.

We know the initial value of a, b, and c is nil, so lets start there.

1
2
3

puts (!nil).inspect   # => true
puts (!true).inspect  # => false
puts (!false).inspect # => true

So each invocation of one “side” of the flip-flop will gracefully handle the initial nil value of the variables, and then swap them between true and false. The flip-flop operator consists of two identical expressions though, so what behavior will that produce?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

a = nil
(1..9).each do |n|
  puts "#{n} #{a.inspect}"
  "Fizz" unless (a = !a) .. (a = !a) # no output here, we just care about the changes to a
end
# =>
# 1 nil
# 2 false
# 3 true
# 4 false
# 5 false
# 6 true
# 7 false
# 8 false
# 9 true

So the flip-flop operator, with just a single state variable, is able to create a pattern that sets a to true every third time! This is exactly how often we want to print “Fizz”!

How does this happen? If the only operation used is negating a boolean, the boolean will return to its original value after an even number of operations. So how are an even number (maybe 2, 4 or 6) of operations squeezed into three runs of a loop? Lets investigate the value of a after each condition of the flip-flop, rather than once per loop. We’ll use two simple functions to print within the conditions of the flip-flop:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# given a value, print its negation, then return its negation
def print_negate1(value)
  puts "a #{(!value).inspect}"
  !value
end

#same as above, but print b instead of a so we can tell
#which condition is being checked
def print_negate2(value)
  puts "b #{(!value).inspect}"
  !value
end

a = nil
(1..3).each do |n|
  puts "#{n}"
  "Fizz" unless (a = print_negate1(a)) .. (a = print_negate2(a))
end

# =>
# 1
# a true
# b false
# 2
# b true
# 3
# a false

As can be seen in the output, the flip-flop operator does indeed cause print_negate to be called 4 times in every 3 iterations. How? The first time through, the first flip-flop condition evaluates to true (nil negated is true), so the second condition is checked, and a is set to false (true negated is false).

The flip-flop is now “open”. It will only check the second condition now. In the second iteration of the loop, the flip-flop checks if should “close”. False negated is true, so the flip-flop does close. Finally, in the third iteration, the flip-flop checks only if it should open. True negated is false, so it stays closed, and the cycle repeats.

There’s one more complication: the flip-flop doesn’t return based on the value of a, but on its internal state. A flip-flop starts “closed”, meaning it will return false. Once the first condition evaluates to true, it is “open”, and will return true until the second conditional returns true, “closing” the flip-flop. So what is the state of the flip-flop after each of the 3 cycles above?

The first time, it starts closed, opens, and then does not close. Because of the unless, this does not print “Fizz”. The second time, it starts open, and closes, but still returns true, since “Fizz” is again not printed. Finally, the flip-flop fails to open at all in the third iteration, and thus returns false. This allows “Fizz” to be printed, exactly when needed.

So an interesting property of the flip-flop is that it returns true if it starts open, but then closes.

Buzz!

After dissecting the logic for printing “Fizz”, we can describe without even reading the code how “Buzz” will be printed: two variables will be used with some flip-flops to create a cycle that repeats every 5 iterations of the loop.

But that description leaves a lot of the details, and in fact there’s quite a bit more to be learned. Looking at line 4 in the original code, the first thing we notice is a new operator, or at least a variation: here there is a familiar flip-flop nested in the second conditional of what looks like another flip-flop operator at first glance. However its important to note this flip-flop consists of three dots (...) rather than the more familiar two (..). What’s the difference? Using our test code from above with this variant tells us:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

a = nil
(1..9).each do |n|
  puts "#{n} #{a.inspect}"
  "Fizz" unless (a = !a) ... (a = !a)
end
# =>
# 1 nil
# 2 true
# 3 false
# 4 true
# 5 false
# 6 true
# 7 false
# 8 true
# 9 false

This variant simply alternates between true and false, meaning it has an odd number of negations in every cycle. Theres not much Ruby documentation on the flip-flop operator, but the Perl documentation describes the difference:

If you don’t want it to test the right operand until the next evaluation, as in sed, just use
three dots (“…”) instead of two. In all other regards, “…” behaves just like “..” does.

The Ruby flip-flop behaves the same way, and therefore will only ever perform one negation per iteration of the loop. Another way to describe the difference: the first flip-flop variant will allow itself to open and close in the same invocation, whereas the second will not.

Instead of instrumenting all 3 conditionals in the two flip-flops for this part of the code, lets see if we can just reason about it, and describe how it works.

First, we recognise the inside of the second conditional: its the exact same pattern as in the “Fizz” line, but with the c variable. We therefore know that it will cycle through returning true, true, false. However, its output is negated, so the second conditional in the first flip-flop is going to cycle through false, false, and true. Lets work through a couple iterations of the loop and see where this goes.

The first time through, b and c are both nil, and both flip-flops are closed. The first flip-flop will evaluate b = !b to determine if it should open. That will set b to true and return true, so the first flip-flop is now open. This flip-flop variant doesn’t check if it should immediately close, so we’re done.

The second time through, the first flip-flop checks the second conditional to see if it should close. We don’t need to work through the logic of the second flip-flop, we know it will return false this time, and so the flip-flop stays open. Remember, the unless statement means we will only print “Buzz” when the flip-flop returns false(is closed)!

We also know the result of the third time through: the flip-flop is open, and again the second-flip flop will return false; the first flip-flop stays open, and nothing is printed.

The fourth time, the first flip-flop DOES close. However, remember that a flip-flop returns true when it transitions from open to closed, so once again we don’t print anything.

On the fifth iteration, the flip-flop starts closed, b is currently true. The first conditional of the flip-flop is evaluated, and the result is false! This means the flip-flop doesn’t open, returns false, and finally, “Buzz” is printed, exactly when we need it.

Fin

Wow, that was some serious thought for just a few lines of code. I’ve put all the example code on Github, feel free to fool around further.

Needless to say, while I enjoyed the exercise, like most of the Perl-isms in Ruby, I won’t be using flip-flops in production code any time soon.

1. If anyone knows or is the author, let me know! ⏎
2. Probably a gross simplification or outright lie. If anyone wants to suggest a more accurate explanation that is also concise, please do! ⏎

Many complain that Git is too difficult to use, and that it’s easy to shoot yourself in the foot. I’d agree to an extent, but in my experience, Git also gives you the tools to fix any problems you cause.

In my mind the most dangerous commands in Git aren’t things like git rebase, because any mistakes you make with already committed data can be fixed (perhaps with a little help from git reflog).

Instead, the most dangerous commands in Git are those that prevent you from getting your data into Git correctly in the first place, those that make the Git history harder to read than it had to be, or those that behave unpredictably and hide too much information from the user.

These commands are quite popular, but I stand firm, you should never use any of them.

git commit -a

On the surface, git commit -a is just a timesaver, and who doesn’t like to save time? In principle, there’s nothing wrong with a command to commit everything at once. But in practice, I find that invariably when using git commit -a, something not meant to be committed will be committed. Big surprise. It might be a harmless console.log, or it could be massive temporary simplification of a critical bit of code.

I like to take a second before each commit and review exactly what is going in. I’ve set up a helpful git st alias that shows me a denser version of git status.

Usually, I’ll use one of my favorite little known Git features, git commit -p (git checkout, git stash, and many other commands also accept the -p flag), which will go through each section of changed code and ask whether or not you want to commit it. It comes with handy keyboard shortcuts meaning you can go through lots of code in only a few seconds, and if anything is there that shouldn’t be committed, you can skip right over it.

git commit -m

There are two reasons why I hate git commit -m.

First, it leads to short, unhelpful commit messages. On any size team (even a team of one), commit messages are one of the most useful ways to record knowledge from that critical time when code is actually written. git commit -m "fixed big" throws that opportunity right out the window.

Please everyone take a second and write awesome commit messages. Did you know Git commit messages have a well established format that all editors will help you with, and allows writing as much of a description as you want? It wasn’t written for nothing.

Second, did you know that Git will sometimes write your commit message for you? It’s true! Whenever you perform a merge that isn’t simply a fast-forward, Git will generate a beautiful commit message automatically. It records which branch was merged into which right in the commit subject, and puts a list of any files that had conflicts in the body. Those are the most likely places where bugs might have sprung up, so the value of keeping track of them should be clear.

You get all this for free, unless you use git commit -m.

git pull

Of the three commands, this is probably the most used. As a result, the negative effects will be felt the strongest. And what bad thing happens with git pull? Nothing less than a permanently confusing history (gasp)! While it’s true that one can figure out what happened with even the most convoluted history, why would you inflict that upon your friends, colleagues, and coworkers if you don’t have to?

So how does it happen? It takes three steps:

1. Work is done by you directly on the master branch (or whichever branch will be pulled from eventually).
2. Someone else also works directly on the branch and pushes their changes first.
3. git pull is run and a merge commit is generated for even trivial and completely independent changes.

Taken on its own, one extra merge commit is not a big deal. But if even two or three people are not working to prevent unneeded merge commits, things get nasty real fast.¹

The dangers of git pull come partially from it’s bloated nature: it both fetches updates from others, and immediately and automatically decides how to reconcile those changes with yours. This should be two steps.

My workflow is to periodically run git fetch. This ONLY updates my remote branches, so I can see what work others have done. Usually, I’ll quickly inspect the changes that have been pushed using another great alias, git lg. Finally I decide what to do. Usually I simply want to make a linear history with my changes coming after the changes I just pulled. git rebase will accomplish this just fine, and then if it turns out the resulting conflict resolution is difficult, I can abort the rebase or start over and know exactly where thing stand.

On the other hand, even with git pull --rebase (which is a more sensible default than to merge), any conflict resolution is done immediately. There wasn’t a chance for you to figure out what sort of changes were just pulled in (are they huge refactorings that will change a lot and require careful analysis? Or were they simple changes that shouldn’t be a big deal), so resolving the conflicts is also hard. And what will the state of your working copy be after you abort the conflict resolution? Good question.

In summary

Everything that I believe makes for good Git usage comes from a few simple rules: understand what is happening under the hood, use source control as a great source of information, and play nice with others.

These are a few things that don’t work with those rules, next time I’ll cover some ways to follow them.

1. For a great example of good and bad merge commits: check out this helpful Gist. ⏎

I learned a lot from those first few flights, and I still learn something new with every flight. That should come as no surprise: pilots that have been flying for decades, and logged tens of thousands of hours in all types of aircraft say the same. I made a few passengers nervous early on¹, but over time I’ve improve not just my flying but my ability to make my passengers feel calm and safe. I’ve had one friend say she overcame her fear of flying commercial just from flying with me once!

As it happens, the FAA allows me to share the costs of flying with my friends, but only under a very narrow set of circumstances. Anything beyond that, and I’m required to at least have a commercial pilot’s license, and possibly comply with even more regulations. This make sense for ensuring the safety we expect of airlines, but would be impossible for pilots flying on their own to afford. I have to say that this allows me far more opportunity to share my love of aviation with my friends than would otherwise be possible, and my flying has improved in the process.

Of course, after the success of companies like Uber and Lyft, it should come as no surprise that someone would try to adapt the ride-sharing model to general aviation. In fact, at least two such companies have appeared: Flytenow and Airpooler. Both companies offered an interpretation of FAA regulations that allow their users to share the costs of travel with their passengers under the same exception that allows me to share expenses with my friends when I fly.

And to their credit, both companies were proactive and reached out to the FAA hoping for clarification and a blessing.

Pilots have been trying to cleverly skirt around these regulations forever (“okay, you fly me to New York for free, but then I’ll buy that pen off you for $500”) and the FAA has always stated clearly that there are no loopholes². So when those of us in aviation who also follow the happenings of tech companies heard about Flytenow and Airpooler, many of us were hesitant to try it out. We all know the regulations (our flight instructors no doubt drilled it into our heads during our training), and there’s no mistake that our license in on the line.

It didn’t come as a surprise to many pilots when the FAA issued their ruling last week: flight-sharing websites violate FAA regulations.

But, of course, governing bodies have come out and ruled against many tech companies. And in those cases many hold the opinion that the laws are wrong, the government is corrupt, and the tech companies are helping everyone by offering a little competition to a stagnant industry. So the same logic should be applied here, and we should all lobby the FAA to allow plane-sharing, right?

Well, not so fast. It’s worth taking a minute and examining if the situation really is the same here.

What good are the regulations anyway?

I’ve always felt that many laws and regulations do more harm than good. Part of the popularity of companies like Uber, and Lyft comes not just from their product itself but from excitement about giving slow-moving monopolies or oligopolies like the taxi companies some much needed competition.

I admit myself I find it interesting that I’m taking this side. But what I’ve also found interesting is that after hours of reading FAA regulations both during and after my private pilot training, I’ve found them to be extremely sensible, if a bit complicated.

It wasn’t always the case, but flying today is incredibly safe. Through decades of work, aviation experts have analyzed every aspect of flying, from everyday occurrences to the most unusual of incidents³. While the taxi industry lobbied to create things like the medallion system and car accidents grew to one of the leading causes of death in the United States, aviation has become dramatically safer over time: the 2010 fatality rate in general aviation is half that what it was in 1970.

Why? As the saying goes: flying is not inherently dangerous, but it is unforgiving. Unlike other industries, where lobbying and public opinion have overridden careful analysis, with aviation the stakes are high, and the consequences of even a minor oversight dire. Things that don’t work have a much harder time sticking.

That’s not to say all in aviation is perfect, but more than any other part of the government I can think of, the aviation industry uses real data and real science to make decisions.

A Question of Scale

Many argued that there is no difference between asking a few friends if they want to go on a weekend flying trip, posting a paper ad on the bulletin board of your local airport offering to share flight expenses, and using the internet, perhaps with a flight-sharing app, to extend the same offer to thousands of people. In some senses, this is true.

However, the key difference, and why the FAA allows a pilot to ask a few friends if they want to go flying, will probably let pilots get away with posting at their airport but might investigate if things get fishy, and flat out refuse to allow dedicated, high traffic flight-sharing apps or websites, is simple: scale.

A well-connected pilot asking many of his or her friends and acquaintances to fly could probably set up a trip almost every weekend. At a busy airport, a note on a bulletin board might allow for a flight both days of every weekend. But imagine a pilot in a big city being able to advertise to a couple hundred thousand people or more. It would be easy to schedule multiple flights every day. There’d always be someone willing to go.

The FAA allows pilots to share expenses as an exception to the otherwise simple rule that a private pilot can’t be in it for the money. This exception is feasible only because it’s expected to apply to a relatively small number of flights. Flight-sharing companies inherently work directly against keeping this exceptional case limited.

Not every industry needs to be disrupted

After the FAA’s ruling, many in tech were concerned. Flytenow quickly replied to the FAA with what I felt was a disappointing analysis of the FAA’s position, and vowed to continue their service with the cost sharing aspect removed. AirPooler reportedly may attempt to reverse the ruling.

I have no doubt everyone involved in both of these companies share a strong love of aviation, and are genuinely trying to make things better for pilots and passengers. I also know how hard it is to build a company from nothing, especially one that skirts the edge of existing laws. And I know that the founder mindset is specifically geared towards conquering obstacles, of which this may just appear as the biggest yet.

With all that in mind, I have a request for the founders of Flytenow and Airpooler: please don’t continue to pursue the current flight-sharing model.

The idea is admirable, and there was no wrong done in testing it out. But the division between a private and commercial license has stood fairly clearly for a long time, and in general it has worked out. Blurring the lines between flying with friends and flying with paying customers will inevitably cause issues.

General aviation currently faces opposition on many fronts. Even aside from what will happen in the case of an accident, there are bound to be cases where the expectations of paying passengers don’t match up with the experience a low-time private pilot like myself can provide. The fallout from these events will be trying for our entire community.

We still need the help of tech companies

The last thing I’m suggesting is that Flytenow or Airpooler close up shop, go home, and call it a day. Now more than ever general aviation needs the help of those of us who have the skills and desire to bring technology to our industry. Everyone among us who can start companies, launch products, and solve problems is extremely valuable.

I couldn’t even begin to list all the ways to improve aviation right now. Just look at the advances in mobile hardware, batteries, sensors of all kinds, and machine learning that are revolutionizing entire industries. And in aviation we have plenty of innovators to inspire us:

• The Foreflight team has arguably made an iPad required equipment and made flight planning easier than ever
• OpenAirplane is making renting planes across the country as easy as renting at your local airport
• PilotEdge has created an amazing network of flight simulator enthusiasts and is helping real pilots practice their skills safely from their own computers
• Even individuals are contributing: developers like Jacob Eiting are making awesome aviation apps, and video series like those from FlightChops are helping more people learn about aviation, and aviation safety, than ever before

Again, I’m not suggesting we halt progress on technology in aviation. In fact I know we’re going to continue going forward. But disruption isn’t the only way to improve. We’ve got some great organizations here in general aviation: we can all make flying more fun, more popular, and safer with cooperation.

1. When you mean to ensure your passengers that despite the somewhat ragged appearance a 1970’s Cessna may have, the engine and components are maintained to the same high level of quality as a new plane, one thing you should never say is: “Yeah, they don’t really take care of these old planes”. ⏎
2. The FAA has ruled definitively on all sorts of schemes: you can’t use your private pilots license to aid your business, even simply flying employees to meetings. You can’t act on a hint from your boss that a ride in your plane will convince him to give you a promotion. You can’t offer your mechanic a free flight to get a reduced rates on your next annual inspection. You can’t even fly your drama teacher in exchange for a more prominent part in the school play. ⏎
3. Perhaps my favorite story is that of United Airlines Flight 232. One of the plane’s engines failed catastrophically requiring an emergency landing. Investigators recovered the critical piece of the engine they needed to analyze the failure, even though they had to search hundreds of square miles of Iowa farmland around where the accident occurred to do it. It was analyzed and despite being damaged from falling several miles, the analysis detected a crack caused by fatigue that lead to the accident. The team then investigated the maintenance and production logs for the airplane going back 18 years, and determined the part was manufactured with the defect, the defect was detected, but the part was not rejected as it should have been. This is the lengths we have to go to if we want to ensure flying is safe. ⏎

I though I had read this book before, but when I sat down to reread it this weekend I found a couple interesting things: 1.) I had never reviewed/rated this book on Goodreads, 2.) I had a bookmark halfway through the book 3.) I didn’t remember any of the content for most of the chapters after my bookmark.

So here goes..

Javascript: The Good Parts made (or at least helped make) the Javascript language. Yes, the book was published in 2008, and yes, Javascript was created in 1995, and yes Javascript was widely used by at least the year 2000. But before The Good Parts, no one was allowed to view Javascript as anything but a toy. Worse, a toy with many sharp pieces that would hurt you if you tried to use it.

The Good Parts is still hard on Javascript, both in the main chapters of the book and in two special appendices cataloguing the Awful Parts and the Bad Parts, and there’s plenty of good reasons to be hard on Javascript.

Part of this comes from Crockford’s personality. While I find him likeable overall he is sometimes a bit abrasive and critical. In one of his talks, he mentions he considers colored syntax highlighting to be a feature “for children”. Beyond making more than a few skilled developers angry, I’m sure comments like these do their share to keep new people out of our field. The “REAL programmers don’t use X” rhetoric is strong enough without people wondering if finding value in syntax highlighting means they aren’t cut out for programming.

I also notice a disconnect between Crockford’s suggested pattern of Javascript usage, and that which is actually common today. Crockford was adamant that the “new” keyword never be used. He suggests we abandon what he called the “pseudoclassical” inheritance features that somewhat resemble C++ or Java, and embrace the prototypal inheritance that he considers to be the core of the Javascript language. At least in the world of Backbone.js, which is the most widely used framework I know of that isn’t trying to rebuild Rails on top of Javascript, but rather work with the language, things have settled on a strange combination where prototypal inheritance handles defining objects that look eerily similar to traditional classes, and then the dreaded “new” keyword is used to intansiate individual objects.

Finally, I can not believe that Crockford isn’t suffering at least a little from a case of Stockholm syndrome. I know this because I’ve been writing Javascript for over 10 years, and have seen my own admiration for the language grow even while I questioned whether or not my admiration was valid.

There IS an elegance in the Javascript language that this book helps unearth, but whether or not that elegant system actually makes Javascript useful is more uncertain. I see the beauty in using closures to hide access to private variables, but is it worth the cognitive load over simply declaring something private?

In any case this book is a must read for anyone doing Javascript development. I don’t think this book has achieved the top status of “must reread every year”, but it seems reasonable that you should read this book twice: once after you first dive into Javascript and want some semblance of clarity after the initial confusion you will no doubt encounter, and then sometime later when you are experienced with Javascript and wish to achieve Zen with the language.

To everyone I met or talked to during the week, it was great to see you.

Speakers! You guys gave some amazing talks and it was awesome to watch you give them and get to chat with you about them later.

And last but not least, to everyone who attended my talk: thanks so much! I hope you had as much fun listening as I did giving it. The slides are here and you can see the video of my talk from MWRC on youtube.

See you all at the next conference!

Today is day 100 and this is blog post number 10. There are a lot of things I’ve learned that I could write about, but one in particular stands out to me.

One of the hardest things in the software world is learning to actually ship what you’ve made. It’s much easier to simply continue working: adding new features, fixing bugs, refactoring. Often the work simply isn’t as fun. Building the core of a new product is great: you’re laying the groundwork, making important decisions about the entire architecture of your software. It’s all too easy to put off the finishing touches that are required if your software is actually going to be usable.

It’s even easier to put off the whole idea of finishing all together. Drawing a line in the sand and declaring your software ready for others to use is difficult. It means admitting things aren’t perfect and that you aren’t going to fix them (yet). Worse, it means exposing those flaws for everyone to see.

Writing, as it turns out, is exactly the same. In fact, it’s even more difficult to ship your writing. The inevitable flaws you expose when sharing your words are deeper and more personal than any code. And most writing is much more permanent than software: once shared, it generally doesn’t change very much, except perhaps to fix a few typos¹.

So, really, blogging has been the best practice for shipping software I could have chosen. I’ve intentionally tried to embrace imperfection. Every one of my posts needs more work. It would have been easier to sit on 10 drafts, unpublished, for all time. And it really would have been for all time, because none of them will ever be perfect.

My hope then, is that simply by forcing myself to ship lots of imperfect blog posts, my writing will get a lot better. I’ll probably never notice this while I’m writing. Every post I ever work on will have flaws, and whenever I’m writing I’ll be focusing on those flaws.

Every once in a while though, I’ll look back on an old post or two. That’s when I’ll see how far I’ve come.

1. Which, I believe, is why engineers invented the wiki. It’s much more comfortable to keep something an eternal work in progress. ⏎

It might seem strange that being granted something I had asked for would be terrible, but given my reaction to the news, it’s the only logical conclusion.

Here’s a short sampling of the things that went through my head: * What if my talk is boring and no one likes it? * What if no one understands what I’m talking about? * What if nothing I say is new at all? * What if I completely fail to prepare? * What if I have a great talk, but poor presentation? * What if I make a bad joke while on stage? * What if I say something that offends a whole group of people and the entire internet disowns me? * What if someone asks a question I can’t answer and makes me look stupid?

Judging by what most other people have written about giving talks, this is par for the course. Public speaking is universally terrifying, causes enormous stress, and take up countless hours of time in preparation. Why then, does anyone bother?

Because there’s nothing better than overcoming new challenges, and talks are full of them.

Giving a talk requires knowing something well enough to teach it to others. It takes hours of preparation, far beyond that which is required just to be proficient. And you can’t just know fragmented pieces: your knowledge has to be complete and orderly so that you can actually teach others.

Giving a talk (for most people) requires stepping well outside your comfort zone. It requires learning new skills that you can, should, but probably don’t use on a daily basis. Stepping into new things requires accepting a lot of mistakes will be made, and requires the confidence and perseverance to continue despite those mistakes. When giving a talk, all your mistakes happen in public, which is particularly unsettling.

Giving a talk requires great delivery. In a lot of ways, what you say is as important as how you say it.

Giving a talk requires a lot of work. More importantly, giving a talk requires a lot of work with a hard deadline. You have to spend many hours preparing, but you can’t spend an infinite amount of time. You can’t practice your talk until it’s perfect. At some point, it’s the day of your talk and you’re as ready as you can be. The trick then, is to prepare efficiently with the limited amount of time you have¹.

I’m learning a lot preparing for my talk. I know I’ll learn a lot more by actually presenting. And overall, the process has been, and will continue to be a lot of fun. All this motivates me to work on my talk, but I have to admit, there’s one thing that motivates me most of all: to be done with my talk.

1. If you think the time between your proposal’s acceptance and the conference is anything but limited, just wait. ⏎

That blog post would have talked about how there are, at any time in anyone’s life, a nearly infinite list of things that could be done, but time to do only a few. It would have concluded with a poignant reminder that everything we do is a choice, and it’s important to consciously choose to do the things most important to us.

Then I read Edmond Lau’s blog post and saw exactly what I wanted to write laid out before me.

It many ways, it would be easy to throw my hands up and never write that blog post. But after thinking about it for a while, I’m more motivated than ever to write down my ideas.

Initially, knowing someone else has written almost exactly what I wanted to write is painful. But there was going to be a blog post out there similar to mine whether I knew it or not. No writer expects everything (or possibly anything) they write to be completely original. So really, confirmation of such a basic reality of writing shouldn’t change anything.

In fact, there’s a reward to reading someone else’s opinion on anything you’ve thought deeply about, even if you haven’t yet published your thoughts, even if you haven’t yet published your thoughts. Having put your own thought into a topic, it’s much more rewarding to read what others have to say.

For me though, the most exciting thought was how I can improve my own blog post based on what I’ve read. I get to examine someone else’s attempt to write about the same topic, and learn from their work. I can focus on the areas I think they missed, or word things in a different way to avoid specific counter-arguments. Every writer puts their own personal touch into their writing; focusing on the differences is better than focusing on the similarities.

So at the end of the day there’s no doubt: I’ll be writing that blog post and many others. And whatever I write will be my own, even if someone else has written about it too.

If you’re using Git (or any other distributed version control), then you have an incredible new power to aid in the understanding of your code, something someone using Subversion (or any other centralized version control) simply doesn’t have. I’m writing all this because I see so few people taking advantage of it.

The advantage is simple: with Git, you can rewrite history.

As a simple example, consider the common “forgot to check in a file” commit. With Subersion, there’s no way to fix this simple mistake, no matter how soon after committing you catch it. For all time one logical group of changes will be split into two places. With git, a simple git commit --amend makes things right¹.

The damage done by not repairing this sort of commit is real: the history of a project is an extremely valuable source of context and understanding. Every commit is a chance to record why something was done, and what it is supposed to accomplish. When reading code, these are arguably the most important questions to answer. Simply looking at code, even well written code, can mean spending time deducing the answers. With a well managed history, the answers are out in the open.

There’s a nearly endless list of ways to create a more valuable history. Most of them are, in fact, widely talked about. Git has cheap branching; use it to keep changes that solve different problems separate. There’s no reason to have a bugfix commit in a feature branch. There’s no reason not to split work on dependencies of a large feature into separate branches.

Commits should be made frequently. Initially, there’s no need for them to have any special meaning or semantics, because commits are infinitely malleable. Take advantage of git rebase and massage your many, disorganized commits created during development into a readable, ordered list of semantically meaningful changes. With practice, these types of improvements can be made quickly.

Invariably, talk of these types of changes seem to devolve into an argument over the concept of an immutable history. The idea is that as with Subversion, all project histories should record every change ever made, in the order they were initially made, regardless of the significance of each change. This is the most basic requirement of source control, but not the only one.

What’s often missed is that with Git, you can have the best of both worlds. Develop your feature however you want. Create dozens of messy, disorderly commits. Use commit messages that convey no information whatsoever. Stow these changes away somewhere. Use a tag, or a branch specifically for changes made during active development².

Now that you know how your code should be written, take just a couple minutes and reorganize, reorder, and coalesce. The details of how the code came to be are no longer important. The priority now is separating changes into logical, semantic units that, when taken in order, come together to make the change in a readable and understandable way.

Everyone on your team will be asking questions your commits can answer. Even future you will ask need reminders about the history of your code. Don’t make anyone have to figure out your code on their own, give them all the help you can! You’re not using Git to the fullest if you don’t.

1. With the usual warning to not use git push --force if it would disrupt others. ⏎
2. An awesome feature of git branches is that they can contain nearly any character, including slashes. I’ve seen projects that use this to split branches into categories. There can be categories for bug fixes, experiments, development, etc. The initial, unstructured writing of code done during early development can certainly be a category. ⏎

I didn’t really care for Ruby’s syntax, thought Bundler, RVM, rbenv, and co were far more confusing than pip and virtualenv¹, and especially thought the entire mantra of writing code to almost read like English was laughable (things like 5.times especially irritated me).

In short, I expected to essentially carry on programming just like before, except possibly with better tools to help me along. That’s not quite what happened.

Initially little changed. My for i in items: was replaced with for i in items do, but did exactly the same thing. But questions started coming. Why did Ruby have do/end AND curly braces? Why were loop counter variables sometimes enclosed in vertical bars? Why did every damn thing include Enumerable?

As I worked with Ruby more and looked around at code written by more seasoned Rubyists, I noticed something even more strange: no one seemed to use for loops at all. It didn’t even save any typing (clearly the most important thing to Ruby programmers), yet items.each do |i| was universally preferred.

Furthermore, Rubyists seemed to hate creating variables. Class methods were short, and seemed to just take an input, massage it in some small way, and – without even the courtesy of an explicit return statement – pass it on to the next thing. My C++ trained brain longed to see variables created simply to iterate through arrays. Instead all I got were calls to map. I found myself using each_with_index just to stay comfortable, without even needing to use an index.

As time went on though, I began to appreciate the conventions the Ruby community had adopted. There was great clarity to be had in concentrating on what was being done – transforming some data –, rather than how it was done – by iterating through every element in some sort of collection and doing the same thing to each element. My code was shorter, but more importantly, it was more obvious what it was doing, and why it was doing it.

Meanwhile, a movement was brewing in the programmer community at large. “Learn functional programming” they said. “Down with side-effects.” “Bow to your higher-order function gods”. I took note to read up on it some time and kept on coding.

Later, as I was also becoming better with Javascript, a language I had first learned a decade before and dismissed as poorly designed, I finally started getting comfortable when I discovered Underscore.js and Backbone and immediately was comfortable with their powerful collection utilities. “Finally, someone has brought the power of Ruby Enumerable’s to Javascript”, I thought.

The functional programming proponents are at least as numerous in the land of Javascript, so this was about when I really decided to take a look and see what they had to offer. To my astonishment, everything I read about functional programming wasn’t talking about anything new, but simply giving names to things I already did.

It was then that I realized many of the things I loved about Ruby weren’t Ruby things at all. They were functional programming things. Underscore didn’t bring the power of Ruby to Javascript, it brought the power of functional programming.

1. I’ve completely reversed that decision and can’t imagine leaving my Gemfiles behind for requirements.txt. It seems silly that one would install packages, then write the list of installed packages to a file for later, instead of just writing a list of packages to install. ⏎