How to Code First with Design-First Benefits

The preference between starting with design or jumping straight into coding often depends on the context of the project, the individual developer’s or team’s workflow and the complexity of the task at hand.

Focusing on design before delving into coding is widely recommended for a variety of reasons. A design-first strategy promotes careful planning and prioritizes the user’s perspective, guaranteeing that all parties involved have a unified understanding of the project’s goals. On the other hand, prioritizing coding fosters agility and swift development and prototyping, albeit at the cost of forgoing some of the advantages of having an upfront design.

Code-First or Design-First: A False Dichotomy

The problem with this supposed choice between design-first and code-first is that beginning with code doesn’t have to mean skipping the design phase, nor does it mean fully implementing the application. Rather, it’s about embracing an iterative approach in which design and development inform and complement each other from the start. By coding early, we can quickly validate ideas, identify technical constraints and refine our design based on practical insights, all while keeping the project’s vision and goals in focus.

What if we could code first and also gain the benefits of design-first approaches by automatically generating visualizations to complement our code?

Many aspects of software development involve abstract concepts or complex systems. Visualization helps break down these complexities into more digestible, understandable parts. This applies across the entire spectrum of a software engineering team, affecting developers, architects, testers and project managers in distinct yet interconnected ways.

When it comes to the abstract concepts of infrastructure, concrete visual representations give each team member insights that foster a holistic understanding of the software itself.

Code First and Leverage Automated Design Visuals

By coding a scaffold or template first and using automated visualizations, teams get a code-first method that doesn’t undervalue design; instead, it integrates design thinking throughout the development process and provides the following advantages:

1. Early Detection and Resolution of Design Issues

Automated diagrams can help identify architectural issues or bottlenecks early in the development process. By visualizing the system structure and dependencies, teams can spot inefficiencies, unnecessary complexities or scalability concerns, allowing for prompt adjustments before these issues become more challenging to address.

2. Enhanced Communication with Stakeholders

Visual representations of the system’s architecture make it easier for all stakeholders, including those with non-technical backgrounds, to understand the system’s workings and contribute meaningfully to design discussions. This inclusive approach to project communication ensures that decisions are informed and reflective of a broad range of perspectives.

3. Agile and Continuous Documentation

Teams can rapidly prototype and iterate on their code, with automated tools generating updated diagrams at each stage. Automating the generation of diagrams ensures that the project’s visual documentation is always up to date. This continuous documentation process alleviates the common problem of outdated diagrams that no longer reflect the current state of the codebase, thus maintaining an accurate representation of the system architecture, data flows and service interactions.

Automating Design Visualizations from Code

The visualization functionality I’ve been describing above is a feature now available in the open source Nitric framework, which gives me an easy way to demonstrate how code scaffolding paired with automated design visualization can help teams. I’ll use a bookstore application as an example, scaffolding the key components with Nitric.

We’re going to create an API for a library or bookstore that handles the storage and retrieval of meta information about books. To accomplish this, we’ll import the following building blocks.

We’ll then use these resources to implement our Rest API using these resources. Here is an example of the POST method and some placeholders for the other methods we’ll need to implement in the future.

With just a small amount of partially implemented code, we are ready to visualize our application’s infrastructure requirements.

👁 Image

Armed with this initial template and visual, we can now jump into design discussions. Because of the dynamic aspect of the visualization, adjustments can be made swiftly and their implications understood at a glance.

Team Collaboration on App Design

While we started with coding, the addition of a diagram shifted the team focus away from individual code analysis to a collaborative discussion on implementation.

As we progressively build out this application, one of the next logical questions for the dev team might be something like, “How will other parts of the app know that a book has been created/deleted/updated?”

The team can quickly refine the code scaffold to include event messaging for book-related actions. Upon creating or removing a book, the app will publish an event, thereby allowing other services to subscribe to deliver future functionality such as reporting, inventory analysis, etc.

With these changes made, the visual updates to show the new design:

👁 Image

Early Design Optimizations for Greater Efficiency

So far, we haven’t implemented any code to handle subscribing to the topics book-created or book-removed. However, through analysis of the visualization we have already enabled our team to begin considering optimizations. In this example, we can start to debate whether we have published different topics for when a book is updated. Depending on the circumstances, it might be a better approach to merge `created`and `removed` to simply `updated`. Alternatively, we could also introduce a new state variable within the message body to capture if it was an update or a created event. This analysis could lead us to reduced costs and a reduction in repetitive code.

Detecting Resource Utilization Issues

Inspecting the design visualization also makes it easy to identify rogue resources that have been declared. For example, the following visualization reflects a code update through which we’ve introduced buckets that store book covers for reading and write access. Our plan is to find a more optimal solution for handling or retrieving covers in the future; perhaps we plan to use a viable third-party API.

A quick inspection of the visualization shows no connections between the `book-covers` bucket and the `books.ts` handlers. We can immediately see that this resource is rogue and adjust as needed before the code is fully built out and well before any costly rogue resources are deployed to the cloud.

👁 Image

Try It for Yourself

Starting a project with a rough code scaffold helps teams move forward quickly, but can often result in design gaps if not paired with the right planning discussions. Automatically-generated design diagrams are the powerful tools that next-level teams use to streamline design, development and maintenance phases of projects.

Teams that use code scaffolds and automatic architecture diagrams gain efficiency and agility so that they can rapidly prototype and iterate. They improve their application quality and reliability by identifying design flaws and bottlenecks early. And finally, they align development more closely to business goals through better understanding, communicating and decision-making in collaboration with business stakeholders.

Test out automated diagramming to get a sense of how this approach can accelerate your next project. You can experiment with tools like Nitric; with its simple CLI, you can quickly generate diagrams by coding a template of the required resources for your application. From there, you’re on your way to fostering a collaborative environment where everyone shares a unified vision of your application’s architecture.