Developing a Framework for Any Project

Photo by Sergey Zolkin on Unsplash

First of all, if you are a software developer and reading this, the word “Framework” in the context of this publication is the overarching principle of business strategies in which we will detail below — not a code library in which you install. That being said, this publication should serve as a resource for designing and developing a product that can be easily maintained and extended by future software developers and domain experts.

Whether you are starting a new project or have a live product, my goal is to help you preserve and optimize functionality and utility. Let’s get started!

Ubiquitous Language

One of the first things to consider, is Ubiquitous Language. Ubiquitous Language is a language based on the software’s domain model that is comprehensible and expressive so that communication between domain experts and developers is unambiguous. Ubiquitous Language is specific to a bounded context, which means the terminology that you use for bounded context “A” may mean something different in bounded context “B”. Ubiquitous Language originates from Domain-Driven Design which we won’t be diving into during this publication but if you’re curious to learn about DDD, I recommend starting here.

Agile Software Development

To put it simply, Agile Software Development is a methodology in which self-organizing teams collaborate to discover requirements and improve solutions. Agile Software Development originates from the Manifesto for Agile Software Development which was created by a team of brilliant software developers back in 2001. More information on the manifesto can be found here. The manifesto basically says that there are four main principles in Agile Software Development:

1. Individuals and interactions > processes and tools
2. Working software > comprehensive documentation
3. Customer collaboration > contract negotiation
4. Responding to change > following a plan

Agile Software Development is also based off of several different software development frameworks, one of which is Scrum. We won’t dive into Scrum during this publication, but I highly recommend it for your next project. To learn more about Scrum, you can start here.

Event Storming

Event Storming is a workshop-based meeting in which software developers and domain experts use sticky notes and a wall for business process modeling. Just like any other meeting, it’s important to have the relevant people present only. The software developers will know what questions to ask, regarding the business process that you are storming out, and the domain experts should be able to provide answers to those questions. After enough data is gathered, you and the others are ready to begin filling out sticky notes in the following categories:

1. Domain event (orange)
   An event that occurs in the business process. Written in past tense.
2. Actor (yellow)
   A person who executes a command through a view.
3. Business process (purple)
   Processes a command according to business rules and logic. Creates one or more domain events.
4. Command (blue)
   A command executed by a user through a view on an aggregate that results in the creation of a domain event.
5. Aggregate (yellow)
   Cluster of domain objects that can be treated as a single unit.
6. External system (pink)
   A third-party service provider such as a payment gateway or shipping company.
7. View (green)
   A view that users interact with to carry out a task in the system.

Sticky notes are then put up on a whiteboard or wall so that the business process can be seen by all.

Example:

Event storming can be repeated for each new business process or feature that your organization needs fleshed out. To learn more about event storming, you can visit https://www.eventstorming.com/ and https://en.wikipedia.org/wiki/Event_storming.

Project Tracking System

A project tracking system allows you to plan for, track, and organize milestones as your project undergoes development. There are dozens of services available on the web. A few popular at the moment are Jira, Monday, and Trello. Choosing viable project tracking software depends on project complexity, team size, and several other factors. It’s ultimately a team decision to determine which is right for you.

After subscribing to a project tracking system, swim lanes and columns make it easy to track the progress of tickets. For a small project and team, you might use Trello and simply have columns: To Do, Doing, Done. For medium to large projects and teams, you might have a more involved workflow in which case Jira might be a good candidate with columns like: Blocked, To Do, Doing, Review, QA, Done.

Version Control System

Version control is the process of tracking and managing changes to your software’s code. A version control system gives you an interface and the tools needed for version control, allowing your team to easily manage changes to your software’s code over time. The term for where your source code will live is a “repository.” A repository is typically created per project whereby a branching strategy is decided on by your team and put in place so that developers are able to continuously integrate code simultaneously by way of pull requests.

Here is a version control specification that has worked well for my team and I in the past:

Base Branches

develop: default branch

main: production branch

Branch Naming Convention

ABC-123-ListUsersAPI: typical feature branch branched off of the latest version of the develop branch where ABC-123 references the Project Tracking System’s ticket number followed by a hyphen and Pascal-cased set of words briefly describing the feature

Pull Request Title

A typical feature pull request should have a title describing the feature prefixed with the Project Tracking System’s ticket number. Examples, “ABC-123 List Users API” and “ABC-123 List Users View”.

Pull Request Description

A typical feature pull request should have a description describing what it is that the PR is doing, followed by testing instructions. Example, “This PR adds an API endpoint to retrieve all users. To test, bring up the project and use curl to execute a GET request to the newly added API endpoint at http://localhost:8080/api/v1/users. The response should contain a list of users.”

Pull Request Reviewers

Anyone who should review the PR.

Pull Request Assignee

Yourself or the developer that worked on the PR.

Merging

A typical feature pull request should have a passing build (GitHub Actions), addressed feedback, and a minimum of 2 approvals before the PR’s assignee merges the PR.

Best Practices

• It’s a good idea to get into the habit of running git pull prior to creating branches so that your created branch has the latest version of its parent branch. git pull should also be ran before writing code on a shared branch for the same reason.
• It’s a good idea to get into the habit of testing your code prior to committing any code. Check for failing unit test and linter errors as well.
• Stay up to date with PR notifications, it’s a good idea to address PR feedback as it comes into your email inbox so that feedback doesn’t pile up.
• If there are more than 6 stale PRs open, feel free to drop a quick message in the team’s communication platform reminding the team to get some eyes on open PRs when they have a chance. I typically do this in the mornings, if necessary.

There is a lot to unpack here, and I’m being fairly presumptuous that you have decided to go with Git as your version control system. I do recommend Git as your version control system as it is free and open source. To learn more about Git, you can visit their website here. Remember, this is but one man’s humble approach to a version control specification. Do your own research and come up with a specification that works for you and your team.

Communication Platform

A communication platform is a service that allows your organization to communicate in real-time. Two of the most popular communication platforms at the moment are Microsoft Teams (previously Skype) and Slack. As always, the decision on which platform to use depends on your organization’s needs. I’m a huge fan of Slack as it does everything that my org needs and then some. Some things to consider when choosing a communication platform:

• User-friendly interface
• Security
• Video messaging
• Screen sharing
• 3rd-party app integrations
• Scalability
• Software reliability and support

Conclusion

I hope this publication was (at the very least) an enjoyable read. If you learned something, I’d love to hear from you in the comments section!

Until next time,

Pascal