Software engineering principles

Up: Ideas for non-fiction writing, Software development

Rough idea: Write down my software engineering principles in detail. Maybe as its dedicated site, continuously updated. Not an article (published only once), and not a book (can’t be updated afterwards).

It might also become a wiki of sorts. Everything in here is connected.

Topics to cover:

• Code reviews
• Delivery and deployment
  • Backwards compatibility
    • Evolving software safely and quickly
• Collaboration and version control
• Documentation
• Security
• Production readiness
• …

To do: This list of woefully incomplete — add lots more!

To do: Sort this by lifecycle stage.

To do: Add stuff from the Software development note.

High-level topics

No idea whether this makes sense. Difficult because all of this is so connected with each other.

• Collaborating with others (or your future self)
• Security, legal, and privacy
• Deployment and release
• Post-release activities (monitoring, bug fixing)
• Dealing with problems (rolling back, reverting, incident response)

Brainstorming

A brain dump. Just a bunch of mostly-unsorted thoughts.

Make only soft decisions

Set nothing in stone. Ideally, each decision can be reverted or modified. Still, make decisions and commit in order to make progress.

Related: Get people on board with (breaking) changes by radiating intent.

Communication and collaboration

See:

• Pull request template

Naming

See Naming principles.

Prioritize

Automate style checking and linting. Code reviews are ideally free from style discussions.

Refactoring

I agree 100% with what Kent Beck said:

for each desired change,
make the change easy
(warning: this may be hard),
then make the easy change

See also: Preparatory refactoring.

Testing

Prioritize functional tests (as high level as reasonable). Move to lower-level tests when the high-level tests are showing their drawbacks (execution speed, mostly).

Fix or replace flaky tests.

Stubbing and mocking — when and when not to. See Week­notes 2023 W19: Stub.

If the test suite passes, then it should be safe to assume that the product has no known defects.

When a regression is found, apply TDD. Also consider using TDD when the problem is well specified and the solution space has been explored.

Avoid relying on details in tests. When testing a generic “product” instance, use a randomized one. Don’t rely on preexisting instances. (This might cause tests to become flaky, but a flaky test is better than a false positive.)

Quick check and mutation testing are worth exploring.

If a test passes, then changing the underlying implementation must cause it to fail. Changing the test (assertions, setup) must cause it to fail, too.

Tight feedback loop

Prioritize code review feedback. <2h is ideal.

Tests need to run fast. Ideally locally, too.

Automation

Automate everything that can be automated and needs to run regularly. Invest in this early to reap the payoff.

ddenv is part of this.

CI/CD is part of this.

Automated testing is part of this. Style checkers and linters are part of this.

Responsibilities of a software engineer

More than writing code. Embrace DevOps. Prioritize code reviews.

Career and success

This is highly dependent on the culture you’re in, but consider what you need to do to stand out.

Sell yourself, even if you do less-glamorous work. That less-glamorous work (e.g. dependency updates) still needs to be done.

Tech stack

Consistency is more important than picking the “right” tech stack.

Expect the tech stack to change over time. Build with migration in mind: avoid lock-in.

Third-party software

Early on, embrace third-party software. Build as little as possible yourself. Once you have product market fit and the product is maturing, figure out where the tech stack is painful and which third-party software to build in-house.

Protect yourself against third party software disappearing. Do not rely on third party repositories only; pull in the source code of third parties.

Keep dependencies up to date. Automatically, if possible. Keep on top of security problems at the very least.

Architecture and design

Keep things as simple as possible. Ask yourself: “would I want to be on call for this?”

YAGNI is generally good.

Do capacity planning. Don’t plan too far into the future. Prefer elastic, easily scalable setups (horizontal scaling).

Abstraction

Do not abstract prematurely. Avoid DRY until the benefits are clear.

Do not design code for reuse right away. If there is a real use case for reuse, consider it. But even then, consider not reusing the code unless the abstraction is super clean.

Reliability

Set up monitoring.

Set up alerts only when you know that you can and will act on them. Do not have non-actionable alerts. Have a runbook for every alert.

Have a reliable test suite. If the test suite passes, be confident that you can deploy/release. Avoid flaky tests.

Gates

Keep the number of gates (PR review, merge, deployment approval, …) low. For each gate, determine what its purpose is. If it is not clear, eliminate it.

Branching and TBD

Keep branches short-lived (in time) and small (in diff size). Rebase eagerly.

Each change to main (and thus each branch) must have a clear purpose and a single purpose.

Write good commit messages. Do not limit yourself to one line.

Use a Pull request template with a checklist. Make a PR self-contained, and have its description be enough to understand the change; do not simply link to an external ticket/issue.

Become familiar with the git blame and git bisect Git commands and have an understanding of how small commits help make these tools useful.

Before pushing a change, run tests locally, and run through the checklist yourself. Do not rely on others to provide you with a sense of safety.

Example of what not to do: Nanoc 4’s original approach which resulted in merge hell. (Though perhaps Nanoc 4 could have done with a full rewrite. Should major versions be rewrites anyway? And pull in extracted packages?)

Delivery

Software only has value once it its in the hands of users.

Have a staging environment that is as close to production as possible. Staging must run the same artifact as production.

Deploy automatically to staging on merge. Even deploy automatically to production; if you are not comfortable, ask yourself why, and find a solution.

Fully automate the deployment process. There should be no need for documentation.

Deploy changes to production but keep them disabled behind a feature flag if needed. (Usually for frontend apps only; backends don’t need it.)

As a developer, also do the deployment, configuration, and monitoring too. This is DevOps.

Make it possible and safe to deploy on evenings and Fridays. If you are not comfortable with that, ask yourself why.

Version control

Git is not the only tool. Consider becoming familiar with other tools. Consider whether Git is right for you.

Fossil? Jujutsu? Pijul?

Keep everything in version control so that you can build old releases without problems.

Every commit must build and pass the test suite. It should be okay for any developer to revert a commit if it breaks the build.

Automerge and merge queues are a great way to keep the main branch passing.

Artifacts

Keep built artifacts around. Especially released ones, so you can roll back quickly.

Artifacts for release should not include any development or testing tools, libraries, or configuration. Only what is strictly needed to run it; keep configuration to a minimum.

Deploying is not releasing

Decouple deployment from release.

The definition of done should be “released.”

Release branches

Not for SaaS.

For anything else, maybe — but try to avoid it. Nanoc wouldn’t use them either.

Alpha/beta/rc versions are only worth it at the very beginning of the software creation process. Not for new minor versions, and not for new major versions.

Release early and release often. Have an automated update process in place for non SaaS tools.

One repository

Keep documentation and code in the same repository. Configuration, too. This allows treating everything together, and even testing documentation for correctness. Keep the web site in the source code too.

Organizational structure

Each team needs to have all the resources it needs to do its day to day job. Small, complete functional teams.

This is necessary for effective communication and a tight feedback loop.

Outages

Roll back eagerly. Revert also, but that’s not a priority.

A rollback should start immediately and not trigger the CI/CD pipeline again. It is not a revert.

All changes must be reversible. Except when deleting dead code, but even then only with special care.

Malleability

No code is final. Don’t get attached to code you write. Others will change it. You will change it.

Design software to be easy to replace.

Configuration

Software should not assume that it has been configured correctly. It should validate those assumptions, the same as with user input.

Related: Parse, don’t validate

Avoid silent failure

Prefer accessor methods for private instance variables, so that you don’t get a silent nil.

Move constant strings into constants and refer to them by constant name, so a misspelling will trigger an error.

Load the entire application at startup, rather than lazily, at least in staging/production.

Load configuration in its entirety, parsed and validated, eagerly.

All of this will help ensure that if the application starts, it will function properly too.

Documentation

A last resort; if you can replace it with something else (eg automation) it’s better.

Test your documentation, automatically.

Create a glossary.

DRY

Only applies if the exact same thing would be repeated for the same purpose, ie if these two things would always change in lock step.