#5: Leave Everything Better Than You Found It
Constant improvement of your surroundings adds up exponentially over time.
The book The Pragmatic Programmer by David Thomas and Andrew Hunt offers this passage about software entropy at the very beginning:
There are many factors that can contribute to software rot. The most important one seems to be the psychology, or culture, at work on a project. Even if you are a team of one, your project’s psychology can be a very delicate thing. Despite the best-laid plans in the best people, a project can still experience ruin and decay during its lifetime. Yet there are other projects that, despite enormous difficulties and constant setbacks, successfully fight nature’s tendency toward disorder and manage to come out pretty well.
What makes the difference?
In inner cities, some buildings are beautiful and clean, while others are rotting hulks. Why? Researchers in the field of crime and urban decay discovered a fascinating trigger mechanism, one that very quickly turns a clean, intact, inhabited building into a smashed and abandoned derelict.
A broken window.
One broken window left unrepaired for any substantial length of time, instills in the inhabitants of the building a sense of abandonment. A sense that the powers that be don't care about the building. So another window gets broken. People start littering. Graffiti appears. Serious structural damage begins. In a relatively short span of time, the building becomes damaged beyond the owner’s desire to fix it, and the sense of abandonment becomes reality.
Senior engineers regularly identify, fix, and prevent broken windows in their projects and teams by leaving everything better than they found it. Here’s how:
📑 Improve Documentation
An important trait of senior engineers is their ability to increase the success of those around them, not just themselves. Interacting individually with another person isn’t the only way to do that. By iteratively improving your project’s documentation, you enable others to easily access information necessary for doing their job successfully.
Add New Documentation
Are you adding a new feature or learning a process that hasn’t been documented yet? Add it for yourself and the next person.
Update Existing Documentation
Is a document you’re referencing wrong or out of date? Maybe a dependency has changed, or a related feature has been removed.
A great time to add or update docs is when you’re new to an organization, team, or project. As you onboard, you’re bound to find something not quite accurate.
Turn Questions Into Documentation
If you have a question that you have to go directly to another person to answer, or if someone comes to you with a question, consider documenting the answer. Not everything needs to be written down somewhere, but be aware of what information you or others are lacking and how it can be made accessible.
💡Expose Hard-to-find Resources
Similar to documentation, sometimes resources and dependencies for your projects are not effectively shared or easily referenced. If you need to go hunting for something you need to do your job, make it so the next person can find it easily on their own.
Share Files & Credentials
Sometimes project files that aren’t committed are passed around directly between engineers. Try to remove these manual processes and ensure everything is shared with those in need.
Commit non-sensitive files to appropriate repositories
Created shared file drives for non-code resources
Utilize password managers to share credentials
And remember, you can implement these things! Bring the solution to your boss and work together to determine how much of their help you’ll need. Your initiative will be recognized.
Improve Logging & Metrics
Are you having trouble debugging, looking for performance insights, or generally investigating your application? Add appropriate logging and metrics.
Is there a lot of noise in the logs or metrics for things that really aren’t valuable? First, check with your team to confirm they aren’t valuable. You may not know the full context. If the team agrees, remove the noise.
👩🏽💻 Clean Up Code As You Go
This is a huge one. Listen up:
You will never be given proper time to address the shortcomings of your code.
The reality is, software development is a means to achieving business value. Business value means customer value. And customers don’t see improvements to technical debt.
(I can feel you starting to argue with me. Of course there’s nuance in every situation, including yours. Forget your argument for a second and listen.)
There will always be something wrong in the code that you would like to fix. Always. And you’ll wish for a sprint or a month to tackle that debt. It will never happen. Instead, clean up code as you go. In small iterations, when you’re already working in that part of the code.
Making iterative improvements to your code as you work around it will significantly reduce the amount of technical debt in your code, without ever needing specific time dedicated to it.
Make it a part of your deliverables. Include a buffer of improvement time in your estimates. Check the code when doing your feature planning to see if you’re going to be touching anything ugly, so you can fix it along the way. You’ll never get a dedicated sprint, but you will get an equal amount of time and then some if you spread it out into each feature and deliverable you work on.
Improvement Opportunities To Look Out For
No tests. Add tests to important parts of your application that aren’t covered. Especially if the code is confusing or complicated – tests help document expectations.
Repeated code. Keep things DRY (don’t repeat yourself).
Hard dependencies. Is changing an implementation or adding test data difficult? Use good abstractions and dependency management.
Difficult APIs. If a dependency is difficult to work with, create layers that can help “translate” the difficult part, separating the calling code from the difficult logic.
All of these will be explained in more detail in future issues of Become a Senior Engineer. Subscribe today, and hit reply to tell me which topic you’d most like to learn about:
⚙️ Implement Processes & Standards
The blending of many engineers and their own styles and opinions often leads to a more complicated code base. If everyone is implementing things in their own way, it becomes more difficult to comprehend and modify. It can also be accidentally insulting (“Why did you change my code? There was nothing wrong with it!”).
Senior engineers recognize the importance of having defined processes and standards that everyone can adhere to. It improves quality and understanding, while eliminating decision making and opinion clashes.
As you run into situations where a difference of opinion or a lack of standard creates multiple possible implementations or confusion, find a single solution the team can follow.
I know – this is harder than it sounds. Those differences in opinion will lead to some arguments. Thankfully, there’s a two step path to success:
Listen to everyone. After introducing your standard, listen to everyone’s responses. Create a shared document and show that you noted their thoughts. People want to be heard and considered – demonstrate that you have done so.
Decide, then iterate. Don’t wait for a solution that everyone unanimously agrees on – it’ll never happen. Pick one that the majority approves of, implement it, and iterate from there based on what the team learns and experiences.
🚫 Teach Your Failures
This one is less tangible than changing documentation or code. The principle is the same, though: leaving your team better than you found it.
Senior engineers still have failures. Sometimes they’re even bigger due to the larger scopes of their projects.
What differentiates senior engineers is:
They are not afraid of failure – they ensure risks are minimal, and have plans if things go wrong
They embrace failing as much as success, in that both are incredible teaching and experience moments
They take their failure and share it with the world
By teaching your failures to your team / organization / blog / newsletter / social media, you add to the collective knowledge of your audience. You position others to eliminate a point of failure before it occurs.
You know not to eat a poisonous fruit or play in poison ivy,because someone before you unfortunately learned the hard way. While less life-threatening, the same is true for your failures on the job.
Audience Questions
✨ 🆓 Answer any of these questions for a chance to win a free book!
What is your favorite piece of documentation?
What recent action did you take to leave your project better than you found it?
What failure did you experience lately that could be a teaching moment? No failure is too small!
Hit reply to answer any and all of these, and I’ll highlight your answers in a future issue!
Happy Thursday, engineers!