Software Engineering Best Practices + The Best Resources to Save🚀

Maybe you're a newbie dev, in a coding academy, or newly graduated. Or perhaps you're old and cynical like me. The reality is, tech moves fast, and it's easy to get distracted by the latest software, tool, or trend.

But while you're floating in YouTube videos, Reddit boards, and StackOverflow, we've got something to keep you anchored: the good coding practices in software engineering. Let's take a look.

Testing

A good developer sees testing as an intrinsic part of their developer experience and their skillset. Testing makes it possible to identify errors, defects, and a bug and to reduce flows. This creates better products. Well, tested software is easier to use, reliable, and of a higher quality.

Code Quality

I've written a lot about code quality in other posts, but I stress that code reviews—especially the use of automation tools and peer previews are vitally important.

Code reviews provide a way to locate problems so that they can be fixed as early as possible. They can also ensure the consistency and reliability of the software you are building.

Documentation

Documentation has been described as writing a love letter to your future self. According to the Write the Docs community, code that you wrote 6 months ago is often indistinguishable from code that someone else has written. You will look upon a file with a fond sense of remembrance. Then a sneaking feeling of foreboding, knowing that someone less experienced, less wise, had written it.

"As you go through this selfless act of untangling things that were obvious or clever months ago, you will start to empathize with your users. If only I had written down why I had done this. Life would be so much simpler. Documentation allows you to transfer the why behind code. Much in the same way code comments explain the why and not the how, documentation serves the same purpose.

Documentation keeps people on the same page, makes it easier to jump back into older code, enables asynchronous collaboration, and helps track and resolve bugs.

Further, Rich Bowen made a great point a few years back that still stands:

The technology world is getting more complicated every day. The list of things that you're expected to know grows all the time, and nobody can be an expert in everything. Expecting that everyone does all of their homework and asks smart questions is not merely unreasonable; it's becoming impossible.

Compassionate tech support—and better documentation—is the only way for people to use your software effectively. And, if they can't get their answers in a reasonable amount of time, they'll use a different solution that has a better-paved on-ramp.

Even better, there are plenty of ways to automate documentation. You can write your documentation in Markdown and use a linter like Vale for style guide consistency and correct easy-to-make errors like grammar mistakes.

If you’re looking for a way to add context to your code but also want to reduce context switching, check out these helpful VSCode and JetBrains extensions that allow you to add issues, comments, and TODOs directly in the editor.

Software Maintenance

Software maintenance is a critical part of the software development lifecycle.

Software developers need to constantly nurture their product to enhance its functionality, reduce deterioration, satisfy users' needs, and ensure the continued success of their product. This is achieved through software maintenance.

Simply put, I like to think that if you spend a good chunk of your life creating something great, you want to keep it functional and healthy. You're proud of your work. Let's keep it that way.

Technical Debt

Most developers get twitchy when we talk about technical debt. It's one of the most significant forms of procrastination. We get it. You're busy, and you let it slide and then a bit more. You also forget about refactoring. And it's all well and good until something happens and the code is so bad it no longer works. Worse, fixing it becomes a major enterprise pulling people away from other mission-critical work and holding up important deadlines.

We're big fans of the boy/girl-scout rule. This means:

'Always leave the code better than you found it.'

In other words, engineers should continuously clean up small pieces of tech debt, so they never have to undertake a giant refactoring project when they're too close to technical bankruptcy.

Little and often my friends. Make it as habitual as cleaning your teeth. Set the alarm every day at 3:30 pm. Automate whenever possible. Whatever works for you, just do it.

To make it easier for your team to track and prioritize technical debt work, use the Stepsize issue tracker in the editor. It helps Engineers create technical issues, add them to your sprint work with Jira integration, and address tech debt continuously.

Being a Good Team Member

One thing that's often absent from typical lists or articles about best software engineering good practices is working well in a team.

There's a legacy trope of the (usually male) virtuoso coder, a loner maverick, who works in isolation, speaks to no one unless it is to say something offensive or sexually harass female colleagues. He manages to get a pass for all his misdeeds as his code is so good it could be read as a bedtime story.

I'm here to say those days are over.

I cringe a bit when I hear the term, coding is a team sport, but it's true. Being a good engineer is about being a good team member. General good work practices like being reliable and honest are important. Also, owning up to your mistakes and not taking credit for someone else's work.

It's about having the ability to prioritize your own tasks and meet deadlines. But it's also about how you relate to others in your team. Do people like working with you? If you aren't sociable, then you can at least be respectful.

Don't be a dick. Is your colleague stuck? Help them! You might feel smug that your knowledge or skills exceed theirs, but it's a bad look for the whole team if something ships with a bug or there's a huge delay. Support newbies, do your share of the boring work, embrace practices like pair programming. All of these make you a good person, as well as a great colleague.

Intentionality and Foresight

This might be a slight deviation from coding as a practice, but I think a good software engineering practice is being a soothsayer.

This means that you create and code with an eye on the future -- how your code and the end product may evolve and change as well as the needs of the end-user. Let me give two examples:

First, let's take security. You've probably heard of the notion of shifting left. This means that good cybersecurity practices are embedded into your code and your products at the beginning of projects. It's security by design, and it's all about prevention, rather than having to pick up the pieces later when you get hacked or discover you've released a massive security vulnerability into the wild.

This means you design software to be secure from the outset to reduce the likelihood of flaws that might compromise a company's information security. A great resource in this area for web devs is the Open Web Application Security Project® (OWASP).

Secondly, accessibility. What are the experiences of your software users? And in the case of product design, your end product? The solution is inclusive design. This approach creates better solutions because it aims to benefit all users. Thinking of accessibility throughout the entire process means you design once for all users, even those with disabilities.

Microsoft has a comprehensive training program on inclusive design. Open Assistive has a great catalogue of open assistive technology hardware and software projects. The WCAG.21 Web Content Accessibility Guidelines cover a wide range of recommendations for making web content more accessible.

Other Resources

I asked a bunch of devs for their input when I was writing this post. Also recommended was Hunt and Thomas' Pragmatic Programmer, The: From Journeyman to Master (I'm the first to say it's a horrendous title, but apparently the information is sound -- tell me if I'm wrong!).

Developer text and video publishers Manning also come highly recommended. Enjoy!

⭐️⭐️⭐️

This article is written by Cate Lawrence—a Berlin-based tech journalist, writer, and content strategist focused on IoT, emerging technologies, and the relationship between people and tech. Originally published at Managing technical debt blog.