Software Development

Note: This post is half-baked. I wanted to put together a robust article about all the aspects of maintainable code... but instead just spat out some thoughts, got bored of the topic, and decided to leave it at that. Sorry. Hopefully it still has some meaning even in this state.

The job of an engineer is not to write code. It is to create sustainable software. This includes:

• Yes, writing code.
• Making sure that code is easy to follow for people who come after.
• Documenting how the systems work together, so others can keep it running and build and scale a technical architecture.
• Communicating with nearby teams.
• Understanding the directions and needs of the larger business.
• Keeping their skills up to date, in order to understand when the product needs to evolve based on changes in tech.

This post focuses on the code, but I recommend keeping a holistic view of what an engineer does because all the other aspects of their job should inform the decisions they make as they write that code.

So what is maintainable code? It is code that can be changed for a reasonable level of effort, with a reasonable level of risk.

Sometimes, hopefully most of the time, those changes are enhancements and updates to the software to make it work better for the organization. But when we talk about how maintainable software is, we also have to deal with the reality that most people are worried about bugs.

Different coders and teams will produce different quantities of bugs. Finding and fixing those bugs is part of the job. To be clear - all code has bugs. All coders write bugs. Coders vary in how many bugs they write and how fast they deliver new features. You could plot coders on a graph with two axes: speed of code, quantity of bugs. You'd end up with 4 categories of coders:

• Fast Coder, Many bugs - Fine - the faster coding balances the bugfixing time.
• Slow Coder, Few Bugs - Fine - the slower delivery is balanced by less bugfixing time.
• Slow Coder, Many Bugs - Not OK. These are the people who are not performing well enough.
• Fast Coder, Few Bugs - Great - this is rare, but the ideal.

There are specific technical approaches to coding that can reduce bugs - type-safe coding practices, re-use of common functions, automated testing and reasonable test coverage.

Other thoughts, not organized...

• Code should be readable - someone new to a section of code should be able to follow it. They should be able to determine how any given piece of code is run, what it does, what inputs it receives, and its output.
• It should not be overly clever - it should use simple syntax and algorithms, and be composed into well-named functions that allow the code to tell is own story of why it exists and what it does. But don’t go overboard on that philosophy...
• Some coders never comment their code because they feel that well-written code doesn’t need comments. That is incorrect - well-written code should not need comment to explain what it does, but it absolutely needs comments to explain why it does it, and what product and business needs led to writing the code in the first place.
• Some of the easiest codebases I’ve worked in had a few small comments throughout any given code file, but entire books written at the top explaining the larger context of where the code in that file fits into the bigger picture and when and why it was written in the first place. This documentation helps future team members understand and update the code, and is a direct contributor to maintainability. It is part of a holistic approach to being an good engineer.

Sustainable software is software that can continue to operate over an extended timeframe, while running under a profitable business model wherein the fees paid by the customers can fully fund the operation of the ecosystem that delivers the product.

Operating a software product over an extended timeframe

Once you get past the initial creation of the software, you have plans in place to actually run the software. This means you need to have the following in place:

• A technical foundation of servers and networking to host the software including the production environment which customers access as well and the background code, servers, and services needed for the organization to operate its internal functions.
• A support structure to communicate with customers to understand their questions, concerns, and needs.
• A product management practice that can understand and prioritize changes needed to the product as its market and technology changes over time.
• An engineering practice that has the ability to operate the product, make changes to the product, and has the resilience to maintain institutional knowledge as the members of the organization change.
• A business continuity practice that covers the ability to keep the business running in cases of emergencies, disasters, and all kind of unforeseen events.
• A corporate structure that handles all governance, legal, financial, and regulatory needs of the market in which you operate, including compensation to members of the organization.
• Communications channels to keep all members of the organization in alignment.

The scale and scope of those elements will vary based on the scale of the software product. In a small organization, some of those bullets points can be as simple as a member of your organization who commits to handling the function. In large organizations, there may be entire departments with formal processes and frameworks in place. The details of those functions are going to vary widely, but if you are missing any one of those bullet points, you do not have the correct organizational structure in place to operate over the long term.

Side note: This is where software consultants tend to fall down. They will often focus on a single piece of this puzzle, but not the holistic need to build a sustainable product ecosystem. They have value and serve a purpose, but they are a tool, not organizational leaders. Use them wisely.

A profitable business model wherein the fees paid by the customers can fully fund the operation of the ecosystem that delivers the product.

Most people can figure out if their organization is profitable - if you bring in more money than you spend for all of the organizational functions outlined above, you are profitable.

But you need to know if your software solution can be profitable before investing the time energy and money to be fully operational. The days of “build it and they will come” are long past. Your business model must include three things:

• Inputs into the system
• Output from the system that hold value for your customer
• At least one specific transaction from which fees are collected from customers.

You’ll find that many software startups miss that last part. There has been a long-held belief that if you find enough people to try your software, they’ll love it and pay for it. But that is not true unless you can point to the output of the product and define a specific fee to charge in exchange for that output.

In most SaaS products, those elements are easy to identity. The input is data from the customer. The output is some type of processing performed against the data, organization of the results of that processing, and visualization of those results to the customer. The value they get is that your software handles that processing so they do not have to devise their own processes. In exchange for that value, they pay you - often a monthly or yearly fees, but we also see per-transaction models as well.

For entertainment - streaming services, video games, etc, those elements also exist. The inputs are the content that has been created. The output is the delivery of that content to your customers. And the fees are the money the customers pay to access the content.

Social media’s elements are a bit different because the primary audience of users of the service are not the customers. They are the input. Input is the existence of an audience whom advertisers want to market to. Output is the delivery of ads to that audience. The transaction is the fees paid by advertisers to the social media platform.

Whatever market and customer base you are targeting, be sure you know the input, output, and core business transaction that is your actual business. And realize the truth of the software industry:

The software is not your business. It is the key tool that enables your business. The transaction you identify in your business model is your actual business.

This matters because in order to make a sustainable software business, you need to understand what that business is. This will drive your decisions when it comes to marketing and sales, your market research and pricing, and your prioritization of engineering and other internal efforts.

Lets start with why a positive environment for building the software matters. Prior posts explain that that the core business is everything other than the software, and the software is just a tool, but that should not diminish the importance put upon building a team who loves making that tool the best it can be.

A positive environment is good for all stakeholders in the software development process - members of the various product and engineering teams will enjoy their work and be satisfied making it a part of their life. The business in turn has a team they can rely on to fulfill the sustainability needs of the organization.

So what is needed to build a positive environment?

In short, you need to build a working environment that matches the personality of your team. In the software world, the teams tend to be comprised of members who are above average in intelligence, have a desire to be engaged with their work, and have a desire to create something new as a result of their work. They tend to want autonomy in their day-to-day work, to be trusted, and to be given a level of responsibility that matches their skills, as well as opportunity to grow their level of skills and be rewarded with increased responsibility, autonomy, and trust.

This is not the same as non-software environments. There are styles of leadership that work in other industries that will fail in software. Autocratic leadership is the one style that will fail almost 100% of the time. Servant leadership works for first line managers. Higher levels of management need to be focused on delegation, direction, and alignment.

My focus is on the product-focused areas of an organization. This includes:

• Engineers whose responsibility encompasses the coding and architecture of the product itself
• Operational staff who keep the systems up and running
• Support staff who communicate with the customers
• Product management staff who research the market and decide what the product needs to do
• Design staff responsibilie for how the customers and other stakeholder interact with the product.
• QA staff who test the product and identify problems before changes are sent to the customers.
• Leadership who keeps all those people in alignment.

Note the exclusions from this list:

• Executive leadership
• Sales and Marketing
• HR, accounting, and other internal corporate functions

I call out those exclusions because their satisfaction with their work environment is often not correlated with the satisfaction of the product team. I’ve seen happy product teams build amazing successful products even when other areas of the organization are miserable. Likewise, I’ve seen products fail when everyone else is happy, but the product team is miserable.

So do you keep those teams happy?

This is no single answer to this. As much as there will be similarities between people who gravitate to software work, we are all different people. The number one priority when determining how to structure your product team and all its processes, communications, and other aspects of its culture is simply to listen. Ask the team how they want to work. Let them work how they want. Let them experiment and self-govern to find their best working environments. Remove people from the team who are blockers to improving the health of the team. Hire people into the team who will fit the team culture they have built. Basically, let them work their way, not yours.

Even so, organizational leaders can put guardrails and requirements on the team. You can define what information you need to hear back from the team in order to understand their progress. You can give them the high-level goals that need to be accomplished. You can express the needs of the business to them. But it should be your goal to give them such requirements at as high of a level as possible, then trust them to handle the details. Your customers don’t care how the sausage is made, and really… neither should you.

At least, in theory. In reality, you do need to know where the team landed on their own organization. Ideally, a senior leader lets the team make decisions that align with the needs that have been communicated, then simply confirm their direction. But sometimes you need to referee. Sometimes business needs force specific internal processes. (Security needs, regulatory needs, etc.)

All that being said, there a few universal truths about a positive software culture:

• Do not rush the team. Some teams are fast, some are not, but if you push them faster than their natural pace, the quality of the product will suffer. Trust your team to know when to take shortcuts, when to put in time, when to make up for past shortcuts.
• Everybody has an opinion about remote work. Build a team who agrees on whether or not they want to be in-person vs. remote. Mixing the two doesn’t work. This choice will exclude specific people from being on the team. Consider that a good thing - there is enough talent in this industry to go around, so if your otherwise perfect team member doesn’t want to match the rest of the team, that is a deal-killer. Hire people who match.
• Do not micro-manage. Software people are rarely, if ever, the type of person who wants that.

Good software does the following:

• Solves a problem - this can include any problem in business or your life, including recreational activities.
• Is sustainable - It continues to work over time. The economics of creating and maintaining it are in balance with the fees charged for the software.
• Is maintainable - It can be reasonably changed in order to adapt to changes in its ecosystems.
• Is supported - The customers of the software can find the help they need when using it.
• Is enjoyable - There needs to be an positive experience not only for the people who use it, but for the people who build, maintain, and support it.

You will note that my list of criteria for good software says nothing about the quality of the code or other technology used to build it. That is a deliberate omission. Good engineering does matter - it supports the points above. I exclude it as its own criteria to force the perspective that software engineering is a tool we use to build software, but is not a goal for its own sake.

Because this can be a contentious point, I want to use the tried-and-true analogy of comparing software dev to a house. Buying a house, in this case. If you saw a house that you loved and wanted to live in, but needed repairs, you would buy the house and fix the problems. But if you saw a house in perfect condition that you did not want to live in, you would not buy that hosue no matter how perfect its craftsmanship may be.

Software is the same - the craftsmanship does matter. But it is a secondary factor, not the primary goal. It makes it a sustainable place to enjoy spending time, only when and if everything already matches your needs.

Another deliberate exclusion from that list is AI. For similar reasons, but with how new AI is at the time I write this, I want to comment on where it fits in good software: Anywhere. AI is a tool, just like code. If you can solve a problem with AI, do so. But do it because it is the right tool for the job. Don't add AI just because it is the latest innovation. That innovation must improve one of the points in the list above. The creation of software is about the result of all the combined elements, not the usage of any specific tool.