Always leave the code better than you found it

Dear new developer,

I’ve spent a lot of my time maintaining working code. I think that is more typical of software developers than working in greenfield development. Yes, there are definitely jobs where you are writing more new code than maintaining, upgrading, bug fixing and improving old code (startups without product market fit being one, consulting being another) but in general code is expensive and folks want to run it for a long time.

Often you’ll jump into code to fix a bug, investigate an issue or answer a question.

When you do so, improve it. This doesn’t mean you rewrite it, or upgrade all the libraries it depends on, or rename all the variables.

You don’t need to transform it.

But you should make it better. Just clean it up a bit. Doing so makes everyone’s lives just a bit better, helps the codebase in a sustainable way, and assists the business by making its supporting infrastructure more flexible.

What are some ways to improve the code when you are in it?

Document

Whether that is a comment that explains something tricky, a larger piece of documentation external to the code which explains how to interact with it, or fixing a typo, trustworthy documentation is key to interacting with code. This is a good way to start improving a codebase because it has minimal impact on the actual code. Therefore it is low risk. But if you’ve ever had a great comment explain a confusing bit of code, you’ll appreciate the time this effort can save.

You can also help documentation by removing old, crufty docs. If you see a comment that doesn’t apply, remove it. If there’s cut and paste documentation which doesn’t apply, get rid of it. That cleans up the code for the next person to come along (who might be you).

Write a test or improve a test

Tests help you write maintainable, extensible code that others can change fearlessly. If you run across code that isn’t tested and you have time and the supporting framework to write one, do so.

Even if it tests simple functionality such as “can I instantiate this object” or “how does this function react when I pass it two null values”, an additional test will help the robustness of the code.

Refactor it

This is one of the most flexible improvements. Refactoring code can range from renaming a variable to be more true to its nature to an overhaul of an entire module. Start small and don’t get wrapped up in perfection. Make the code clearer in intent.

It’s easy with refactoring to get wound around an axle and make too many changes and end up with broken things. Timeboxing is one technique I use to avoid, or at least minimize, my tendencies toward this when refactoring. If all I have is 30 minutes, I’ll make my changes smaller in scope.

A warning about refactoring. Don’t refactor what you don’t understand. Don’t drive by refactor. Discuss your plan with someone more familiar with the code; git blame is your friend. Especially if the code is not well tested, you want to make sure you don’t do more harm than good.

Upgrade a dependency

It’s sometimes a winding path, but upgrading your dependencies regularly is a good way to maintain the code. I remember working in a fork of struts. It was an important application for the company, but we didn’t spend the time upgrading the dependencies, because it was too painful. Eventually, parts of the code became harder to update. The entire application couldn’t benefit from newer technologies and paradigms because of the older dependencies holding it back.

It never feels good to spend time updating a dependency; to me this always feels like running in place. But if you don’t do so, eventually dependencies will end of life and you’ll be forced to update. That’ll be even less pleasant.

How to do it

Based on feedback (this comment, among others), I added this section on Nov 28.

When you are making these changes to improve the code, you’ll help out code reviewers and your future self by making changes that are improving the code separate from changes that add functionality. Whether you do this in separate pull requests, tickets, or commits depends on your team culture. Ask about that. But such separation will make it easier for people who aren’t familiar with the changes to understand them and give feedback on them, whether that is a code review this week or someone reviewing this component two years from now.

Why do it

All of these actions not only help others because they improve the quality of the code, they also provide examples to other developers on how to do so. For example, it is far easier to write the second test in a suite than the first. You can cut and paste a lot of the setup code and tweak only what is different. The first bit of documentation will inspire more.

Code isn’t everything, but it is an important work output. Whenever you touch it, you should strive to leave it in a better place that it was before you did so.

Sincerely,

Dan

You’re gonna be OK

This is a guest post from Jerome Hardaway. Enjoy.

Dear new developer,

So, you’re in the office, learning a million things a minute that you were never exposed to. Everyone around you seems super competent and you don’t want to take time away from them, but you have no idea what you’re doing. You feel like you should probably be a janitor instead of working on a million dollar web app. I’m here to tell you, you’re wrong.

Every person who seems competent has felt like you or still feels like you do, they are just better at hiding it. I know people who have been doing this work for years and feel silly at least once a week. Hitting your head against the tech wall is a rite of passage here and normal and whether they tell you or not, we have all been there. We have all either accidentally taken down prod, nuked the repo, felt lost, accidentally ran up the AWS bill, and just straight up sucked at this job. So long as you focus on having more good days than bad, you will be fine. More than that, you’ll do great, so relax cause we are all rooting for you.

— Jerome

Jerome Hardaway is a Developer Advocate at Quicken Loans and Executive Director at Vets Who Code, Where they help veterans get jobs in software by teaching them how to program for free.

Seek feedback loops

Dear new developer,

Feedback loops are so important. (If you’re not sure what that is, I’d recommend “Thinking in Systems”.)

These loops help systems improve. If you don’t have feedback, you’ll improve more slowly, in my experience. Why? Because you won’t know what you are doing that is good and what is garbage. It’s really hard to evaluate that kind of stuff yourself. You can do it, it just takes time and perspective.

And of course, you want to do more of what is good. Here are some kinds of feedback loops which have helped me.

tests
one to ones
public writing
being a contractor

Automated tests are a really tight feedback loop. You can make changes to code and know if you’ve blown things up. (Type systems are another tight feedback loop preferred by some.) This is helpful in many situations, including when you are debugging a problem.

One to ones are a great way to gather feedback from your manager on problems, challenges and situations that you have faced. By doing it in a one to one (rather than a one off meeting), you’ll build context and history around these. After all, the tenth time you bring up the fact you find front-end development challenging indicates that this is a pattern, and you should evolve yourself or the position to help with the challenge. When you have your meeting, make sure you ask for feedback explicitly. When you get it, avoid being defensive. If you make it hard to get feedback, you’ll get less.

Public writing, especially a blog, is a great way to get feedback. You’ll be able to put your thoughts out in public. This can be scary and frustrating; some communities are more gentle about feedback than others. But the act of writing forces you to make the implicit explicit. And sharing that knowledge is a great way to get feedback. (Even a lack of response is feedback; what you were writing didn’t resonated with the audience you shared it with.)

I think everyone should try being a contractor. First it makes you appreciative of everyone else in a business, because when you are contracting, you often have to take on roles outside of development (sales, accounting, marketing). But for the purposes of this post, contracting is a great way to get feedback from the market. You’ll learn about which skills are in demand and what organizations will pay for those skills. Of course, you can find this out as an employee, but if you are a contractor, especially a short term one, you’ll be interacting with possible hiring managers much more often than as an employee. And the feedback loop is brutal and blunt: do they hire you or not.

Feedback loops are a key way to find out whether what you are doing is working or not. Seek them out.

Sincerely,

Dan