Back-End Development Best Practices Checklist

Development is an iterative process, and so is learning and applying what you learned from previous iterations. You won't meet all these items at first, and some may not apply to your project. Each time you revisit a project, review the checklist below and select a few items to improve.

Use this checklist not only to strengthen your technical skills, but also to improve the reliability, maintainability, security, and sustainability of the services you build.

Architecture & Project Structure

• Choose an architecture appropriate for the workload (serverless, event-driven, API-based, or service-oriented).
• Organize repositories and directories in a predictable structure that separates infrastructure, application code, configuration, and tests.
• Favor managed or platform services when available to reduce operational overhead.
• Use clear naming conventions for services, functions, APIs, and resources.
• Avoid tightly coupled systems; design services that are modular and independently deployable.
• Document architectural decisions and major design patterns used in the system.

Version Control & Collaboration

• Store all application and infrastructure code in a Git repository.
• Commit changes frequently with clear, meaningful commit messages.
• Use branches for features, experiments, and fixes.
• Use pull requests for collaboration, peer review, and knowledge sharing.
• Avoid committing generated artifacts, secrets, or local environment files.
• Keep repository history clean and understandable so future maintainers can understand why changes occurred.

Infrastructure as Code (IaC)

• Define infrastructure using Infrastructure as Code templates rather than manual configuration.
• Use standard frameworks or vendor-supported tooling for defining infrastructure.
• Keep infrastructure definitions versioned alongside application code when appropriate.
• Organize templates so environments and shared resources are easy to manage.
• Use parameterization and configuration files to support multiple environments.
• Avoid manual modifications to deployed infrastructure that are not reflected in code.

GitOps & Continuous Integration / Continuous Deployment (CI/CD)

• Use automated pipelines to build, test, and deploy applications.
• Ensure pipelines run validations, security checks, and automated tests.
• Promote changes between environments through controlled deployment stages.
• Avoid manual deployments whenever possible to maintain reproducibility.
• Ensure deployments are predictable and easily reversible.
• Keep pipeline definitions versioned and documented alongside the codebase.

Resource Tagging & Environment Management

• Apply consistent tags to all cloud resources for ownership, cost tracking, and operational visibility.
• Use the St. Thomas tagging policy to maintain consistent tagging across projects.
• Ensure development, staging, and production environments are clearly separated.
• Avoid hardcoding environment-specific values in application code.
• Use configuration management and environment variables for runtime settings.
• Review resources periodically to remove unused infrastructure.

Performance & Scalability

• Design services to scale automatically where possible.
• Use caching strategies to reduce repeated computation or external requests.
• Prefer event-driven and asynchronous processing when appropriate.
• Monitor latency and throughput to identify bottlenecks.
• Avoid unnecessary dependencies that increase cold start times or execution overhead.
• Optimize database queries and API interactions to reduce unnecessary processing.

Security

• Never store credentials or secrets directly in source code.
• Use managed identity and access controls to grant only the permissions required.
• Encrypt data in transit and at rest where supported.
• Validate and sanitize all external input before processing.
• Regularly update language runtimes, dependencies, and libraries.
• Monitor systems for unusual activity and security alerts.

Coding Standards

• Follow language-specific style guides and maintain consistent formatting.
• Write modular, reusable functions or services that perform a single responsibility.
• Avoid overly complex abstractions that reduce readability.
• Use linting and formatting tools where available.
• Document complex logic with comments or lightweight documentation.
• Favor clarity and maintainability over clever or overly compact code.

Testing & Quality Assurance

• Write automated tests for core business logic and critical workflows.
• Include unit tests, integration tests, and where appropriate API tests.
• Use mocks or local service emulators when testing dependencies.
• Run tests automatically during continuous integration pipelines.
• Test failure scenarios, retries, and edge cases in addition to successful paths.
• Ensure deployments do not proceed when tests fail.

Monitoring, Logging & Observability

• Implement structured logging that provides meaningful operational information.
• Use centralized log aggregation and monitoring tools.
• Capture metrics such as request volume, latency, errors, and system health.
• Create dashboards and alerts that notify responsible teams of failures or anomalies.
• Trace requests across services when possible to identify performance issues.
• Review logs and metrics regularly to detect issues before users report them.

Deployment & Maintenance

• Use automated deployments to ensure consistent and repeatable releases.
• Ensure deployments are predictable and reproducible across environments.
• Maintain clear rollback strategies in case a deployment introduces issues.
• Regularly review application performance, logs, and operational metrics.
• Remove unused code paths, outdated dependencies, and deprecated services.
• Plan for long-term maintenance, including ownership and lifecycle management.

Documentation

• Provide a project README describing purpose, architecture, setup steps, and deployment instructions.
• Document APIs, data flows, and service integrations.
• Record architectural decisions and reasons behind technology choices.
• Include instructions for running tests and local development environments.
• Ensure documentation is updated as the system evolves.
• Clear documentation reduces onboarding time and improves long-term sustainability.

AI-Assisted Development

• Use AI tools to assist with scaffolding, documentation, debugging, and refactoring.
• Use spec-driven development to define requirements before generating code.
• Maintain steering documents that provide AI systems with architectural context, constraints, and coding standards.
• Avoid implementing AI suggestions that modify infrastructure, account configuration, or resources outside the application's scope.
• Avoid accepting changes that fall outside the application, framework, or developer responsibilities.
• Review AI-generated code the same as human-written code.
• Use peer review or code review when adopting significant AI-generated changes.
• Ensure generated code follows established security, testing, and operational standards.
• Maintain responsibility for the final design, implementation, and quality of the system.