everything 'as Code'

Introduction

In his book, “Built To Last,” Jim Collins delves into the characteristics that distinguish genuinely great companies. One underlying theme is the importance of embedding expertise directly into processes. By doing so, companies can scale more efficiently, adapt quickly to change and innovate rapidly. Those same attributes are shared amongst effective software development teams.

Teams that embed expertise into building and deploying code can rapidly address bugs and deploy new features. Over the past decade, Continuous Integration/Continuous Delivery (CI/CD) pipelines have become indispensable because they do precisely that: CI/CD pipelines embed expertise into the software release process. Hours are saved every time code is published to a repository, initiating an orchestra of automation: code formatting, testing, building and deployment.

There is more to software development than lines of code. Diagraming, documentation, procedures and environment configuration are all critical facets. There is an ongoing trend in software to have more “as code” solutions. The trend is fueled by the benefits of CI/CD pipelines being realized across the entire software delivery landscape. As each facet is migrated into the CI/CD pipeline through “as code” solutions, teams are freed from auxiliary tasks and can be re-focused on the work that matters, addressing bugs and releasing new features.

The “As Code” trend is just getting started.

📄 Documents “As Code”

Documents are a vital part of any software project. They are the primary means of communication between team members and stakeholders. They are also the primary means of communication between the software and its users.

• Godoc: If you are writing a module in Go and follow some basic commenting conventions, you can generate documentation for your module automaticlly with a single command.
• Hugo is a static HTML site generator. The blog you are currently reading was in fact written in Markdown and generated using Hugo.
• LaTeX is a document preparation system. It is used to create reports, books, and letters. It is based on the idea that the author should be able to focus on the content of what they are writing without being distracted by its visual presentation.

📐 Diagrams “As Code”

As the complexity of software increases, diagramming becomes paramount to managing the solution and helps teams understand relationships and dependencies. However, diagramming is often more art than science, resulting in an inconsistent representation of systems and information. Size, colour, location, labels, arrows and other visual elements are used at the author’s discretion, producing conflicting diagrams from one author to the next.

Diagrams as Code distill the art of diagraming into a science. Diagrams are generated from text files describing relationships and dependencies, ensuring consistency and maintainability.

• Mermaid is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

1sequenceDiagram
2    Alice->>+John: Hello John, how are you?
3    Alice->>+John: John, can you hear me?
4    John-->>-Alice: Hi Alice, I can hear you!
5    John-->>-Alice: I feel great!

• Diagrams lets you draw cloud system architecture using Python code. It can generate some very good looking diagrams in a language you already love.

• C4 Model captures an aspect of diagraming that is overlooked; context. The diagram should be dependent on the context of the audience. C4 modeling is a set of conventions for diagramming software architecture. It is a simple, hierarchical way of thinking about the static structures of a software system in terms of containers, components, and code.

⚙️ Process “As Code”

The idea of process as code should be synonymous with automation. Tools like GNU Make, AppleScript or Github Actions are all examples of syntax that automate the execution of tasks, often as a script or high-level configuration file. The overall trend is shifting towards more declarative syntaxes that address modern use cases and are system agnostic.

• Taskfile.dev is a task runner designed to be simpler and easier to use than Make. It is written in Go and has zero external dependencies. It is a great tool for automating tasks in your development workflow. I particularly like the ability to have it watch files for changes and rebuild only the assets that have changed. Here is an example task I wrote for building a Go application that implements a plugin framework. Notice how tasks have nested dependencies.

 1# https://taskfile.dev
 2version: '3'
 3
 4vars:
 5  GIT_COMMIT:
 6    sh: git log -n 1 --format=%h
 7  BUILD_TIMESTAMP:
 8    sh: date -u '+%Y-%m-%d_%I:%M:%S%p'
 9  CONFIG_FILE: '{{.CONFIG_FILE | default "/etc/StarCatcher/config.yaml"}}'
10
11tasks:
12  build:
13    desc: Build StarCatcher
14    deps:
15      - task: build:tui
16      - task: build:server
17
18  plugins:
19    cmds:
20      - echo "building plugins"
21      - go build -buildmode=plugin -o plugins/CreateOrder.so plugins/CreateOrder/main.go
22      - go build -buildmode=plugin -o plugins/CreateInvoice.so plugins/CreateInvoice/main.go
23    sources:
24      - plugins/*/main.go
25    generates:
26      - plugins/*.so
27    method: timestamp
28
29  build:tui:
30    cmds:
31      - echo "building tui"
32      - go build -o tui -ldflags="-X main.buildId={{.GIT_COMMIT}} -X main.buildTime={{.BUILD_TIMESTAMP}}" cmd/tui/*.go
33    sources:
34      - cmd/tui/*.go
35    generates:
36      - tui
37
38  run:tui:
39    deps: [ build:tui ]
40    cmds:
41      - echo "running tui"
42      - ./tui -configFile={{.CONFIG_FILE}}
43    interactive: true
44
45  build:server:
46    deps: [plugins]
47    cmds:
48      - echo "building server"
49      - go build -o server -ldflags="-X main.buildId={{.GIT_COMMIT}} -X main.buildTime={{.BUILD_TIMESTAMP}}" cmd/server/*.go
50    sources:
51      - cmd/server/*.go
52    generates:
53      - server
54
55  run:server:
56    deps: [ build:server ]
57    cmds:
58      - echo "running server"
59      - ./server -configFile={{.CONFIG_FILE}}
60    env:
61      AWS_PROFILE: StarCatcherProfile

• AWS Step Functions is an AWS service allowing business logic to be implemented as state machines inside a serverless framework. Step Functions represent a powerful paradigm shift that can bring elegance to complex business processes. Imagine your company has a subscription management service, payment processor, marketing system, CRM solution and a public-facing website; how do you ensure these systems are consistent and coordinated as you onboard a new customer? What if you want to change the payment system for a better rate? By implementing the business logic with AWS Step Functions, you can pivot or evolve business processes under SVC that incorporate regression testing and performance monitoring across the complete onboarding process.

The Future

One of the benefits of this trend is that the syntax for “as code” solutions are often much easier for LLM-based models to produce. LLM models will stand poised to streamline development pipelines, optimizing processes and predicting potential pitfalls, thus ushering in a new era of ultra-efficient software delivery.