Ask smart questions

Dear new developer,

Asking questions well is one of the best ways to learn quickly. You can ask questions of the code, of other people or of search engines like Google. Here are excerpts of my two favorite posts about asking questions.

First, How To Ask Questions The Smart Way:

If you are trying to find out how to do something (as opposed to reporting a bug), begin by describing the goal. Only then describe the particular step towards it that you are blocked on.

Often, people who need technical help have a high-level goal in mind and get stuck on what they think is one particular path towards the goal. They come for help with the step, but don’t realize that the path is wrong. It can take substantial effort to get past this.

This is a very long doc oriented towards helping people ask questions about technical issues in a way that will get them answered by busy developers. But there’s a lot of useful, if blunt, information, including how to look through Stack Overflow, how to ask on a mailing list, what to include and what to exclude, and what to do if you don’t get an answer.

Second, Ask the Duck:

One of Bob’s superintendants was in his office. He was grinning like a bastard around his toothpick. “Andy,” Bob said, “I don’t want you to pray to the duck. I want you to ASK THE DUCK YOUR QUESTION.”

I licked my lips. “Out loud?” I said.

“Out loud,” Bob said firmly.

Preparing to ask a duck, or really just writing up your question in enough detail so you’d feel comfortable posting it on a mailing list or Stack Overflow, often leads to you answering your own question. Sometimes the answer doesn’t come, but additional veins of inquiry pop up (“Ah, so I didn’t investigate upgrading that library, I should try that”), which sometimes lead to the answer. Or to a more intelligent question.

There’s a tradeoff of course. Doing the research to ask a good question is time consuming and can be frustrating. I always recommend asking people you are working with how much time to spend making this kind of effort. If the project is on a short timeline, it may make sense to ask a less prepared question more quickly, especially if it is to an internal team.

So, in a meta way, be prepared to ask questions to determine how much time to spend preparing to ask questions.



Don’t make the same mistake twice

Dear new developer,

“To err is human”. We all make mistakes.

A few years ago I was working on a contracting project with a new version control system. I didn’t take the time to understand all of the commands, but just dove in and started writing code. A few days in, my branch was weird and was missing some code present in a co-worker’s branch.

Turns out I’d been pulling down remote branches incorrectly and creating new branches instead. Whoops!

I made that mistake once, and never again. I corrected that mistake at two levels. First I learned the correct command. Second I learned that a version control system is worth spending some time getting to know. I invested some time learning about this system and how to perform common operations.

Ways you can avoid repeat mistakes:

  • when you make a mistake, make sure you understand what the mistake was
  • find out if there was a second or third level of the mistake, as I did above
  • write down your mistake, either publicly or privately, so that you and others can avoid it in the future

Mistakes happen, no one is perfect. But the goal is to always make new mistakes, not the same mistake again and again.



Over-index in your first few months

Dear new developer,

It is unfortunate, but first impressions matter. And, like any other job, a developer position is in large part based on relations with other people. Therefore, it behooves you to bring your best self to work for the first few months of any job. That doesn’t mean you get to check out later, but in the first few months you should stand out. Some ways to stand out:

  • Arrive on time, or a bit early.
  • Do the extra research.
  • Take on the extra work (not too much–don’t set yourself up as a punching bag–but some).
  • Own your mistakes, but don’t beat yourself up when they happen.
  • Be unfailingly polite.
  • Don’t make the same mistake twice.
  • Ask for your manager’s time and make sure you and they are on the same page regarding goals. How often? Ask.
  • Write that extra bit of documentation to make the next hire’s onboarding easier.
  • Anything else you can think of.

Once you have the reputation of a hard, smart worker, it is hard to lose. After a few months, you can ease off, partly because you have gained the reputation, partly because you’ll actually understand the job better so will be able to do it with less effort.

When you first join an organization, everyone is excited. If you can over-index and achieve 105% or 110% of what they expected of you, the team members will continue to be excited. Consider the alternative where you only deliver 90% or 95% of what they expected. They’ll remember you as pretty good, but maybe a bit of a disappointment.

Either way, that first impression can last for years and can follow you around the organization (and beyond). Choose wisely.



Learning to read code is more important than learning to write it

Dear new developer,

Coding is fun! You get to take a few words on a page, breathe life into it through your understanding, type rapidly into a text editor, and display it to our colleagues. It’s an amazing profession that is changing the world.


The vast majority of code is read far more often than it is written. This is true for a few reasons:

  • Companies pay for code. Code is expensive. They want to amortize the costs of writing it across as many years as they can.
  • Business requirements change. That means that the code that supports those business actions needs to change. But before that software can change, the modifier needs to understand what is currently happening. Even if the requirements dictate a whole new feature is implemented, the developer still needs to understand how the new feature fits into the existing codebase.
  • Bugs occur, where the software is almost correct, but not quite. Again, anyone fixing the bug needs to understand what the existing code is doing.

And over the years, there will be many changes and bug fixes.

There is, to be true, the occasional piece of software that is just “set and forget” where changes are minimal over the years. I once was responsible for a piece of software that ran for five years with no changes. That’s rare enough that it sticks in my mind.

So this means, that of the time you actually spend coding, it’s likely that more of it will be spent trying to understand existing code in order to make changes to it than it will be writing new code. And of the applications you support, more of them will be already written than not. Of course, depending on what company you work for, things might be different. A startup with no existing systems will need more new code than a running business. (I wish I had numbers to support these statements, but all I have is my experience.)

What does that mean for you, new developer?

It means that spending time learning to read code is a good idea.

When I approach an existing project that is new to me and need to have an understanding of it in order to make changes, there are a few different aspects I consider.

  • Scanning. This is the high level overview. What problem does this code try to solve? What language and/or framework is it using? Is it using them in an idiomatic manner, or in a unique way? What are the big pieces of the application, and how do they fit together? This information is perfect for a document, but sometimes needs to be pulled from someone’s head or from the code (you should write down what you learn).
  • Diving down. This is where you focus on the problem at hand, and try to identify where the changes should be made. This will probably involve having multiple files open and moving between them, and trying to understand all the logic of this part of the system. You can also look for more granular patterns in the code, including different levels of abstraction, homegrown libraries or frameworks used, and coding idioms. Consistency matters, so you want to write in the style of the current codebase (which doesn’t prohibit you from noting where the current style is flawed and should be changed).
  • Use the scientific method. Write a hypothesis, make small changes and see what happens. If you can make changes in a staging system or on your local machine, that’s great.. A debugger is super helpful here, as are unit tests (or any kind of automated test). If you can’t make a local copy of the entire, you can typically still set up the language runtime locally and run various chunks of code to get a better understanding of what the system is doing.

Beware of the temptation to try to understand the entire system before making any changes. Whether you need to do so is based on how entwined the system is, how well the system is tested, and how critical the system is. Only discussions with the business and other members of your team can determine the best course forward, but an understanding of the entire system will likely only come with time.

Also, beware of the temptation to just throw away the old code and rewrite it. Especially if you don’t understand all that the code is doing. Old code is reified knowledge, and you ignore that at your peril. See obligatory link to the classic post “Things You Should Never Do, Part I”.

Reading code is more important than writing code because software systems spend the majority of their lifetimes after launch, and change happens.



Learn a text editor

Dear new developer,

As I mentioned before, the raw “stuff” of software is primarily text files. Actually, the foundation of software is ideas and information, but unfortunately a computer can’t yet run on those. So you will need to create text files.

Learning a text editor will serve you well in building software.

Why a text editor rather than an IDE? (An IDE combines a text editor with other tools that help development, including tools that help testing and tools that help debugging. It stands for “Integrated Development Environment”.) Text editors can be used for any language, whereas IDEs tend to focus on one or a few. Text editors can be run almost anywhere, whereas IDEs can only be run on your local system. And using a text editor will force you to become more familiar with the command line.

For those reasons, it’s better to become familiar with a text editor. There are many options, but two really good ones, with long lineage and a large amount of functionality, are vi and emacs. But there are plenty of good options. (Most text editors have extensions that help with certain aspects of development, and it’s worth spending some time research and installing them.)

What if you learn the wrong one? “What if I learn the wrong xxx?” is a question you’ll face many many times as a developer. Since you don’t know the future, you’re always gambling when you invest your time to learn anything. But every time you learn one thing (in this case, a text editor), you have more context and understanding about that “thing”. This knowledge makes it easier to pick up the next text editor, map its functionality to what you previously worked with, and get going more quickly. You also learn the jargon around the technology, which makes it far easier to use Google or some other search engine.

Text editors are easy to learn, but difficult to master. It is often easy to open a file, write something and save the file. But to be able to easily navigate between files, move around a file, or do a mass search and replace, you’re going to have to put in some effort.

But there is no better way to convert thoughts into files.



Learn Version Control

Dear new developer,

If in doubt, put it under version control.

Version control is a way for you to keep track of the core nuts and bolts of code, which are files on the filesystem. Version control lets you make mistakes, err experiments, and roll back time to when things worked. Version control lets you see who made what changes when to which files, so that when you need to find out who to ask about the bizarre function in class XYZ, you can.

Don’t be surprised if that person is you.

There are many systems of version control. What you use depends on your needs, the most important of which is how many people are interacting with your system. But something, even a crufty old system, is far better than nothing.

There are plenty of free version control systems out there, so if you aren’t using something, set up one of the free ones (or better yet, use a hosted service) and give it a try. Github, bitbucket, gitlab, all are happy to walk you through how to store your code in their system. Learning one of the modern version control systems will help you integrate into any team, because running a software project of any size without version control is a foolhardy endeavor that only is typically tried once.

There are some items that don’t belong in version control. Large binary files belong on a storage system like S3. Secret information, like a password, is better kept out of version control and in a secrets manager or environment variables. Documents that are going to be edited by nontechnical users should probably use a shared document repository (which will likely have versioning built in, but hidden).

But everything else, all the source code and build scripts, all the infrastructure setup and documentation, all the assets and sql scripts, those should be kept in version control.