The Building Blocks To Writing Good Code

Speak with any software developer about how they structure their syntax and code and you’ll get 10 different answers. Especially if you are using a language like javascript (not type-safe) vs Dart, which is a type-safe language. While guidelines on how to write good code range widely, below are some good principles and practices you can follow:

Proper Indentation and Comments

It is very important that the code you are writing is readable for other programmers too. When dealing with a team or open source project where collaboration is key, using proper spacing along the logical code components allows the project to maintain a sense of consistency.

If you are using functions to retrieve data, or use third party API libraries to get the data, add comments where appropriate on top of those code snippets, so that if another person tries to analyze your code, or build other functions based upon your logic, they can grasp what is happening quickly and can reuse your work.

Hybrid Repo (Not too Monolithic Not Too Modular)

The Mono-repo vs Hybrid-repo debate never ends. But why not sure the best of both worlds. When I build my repos, I use a hybrid approach that looks something like this.

• Core
• Light Modules (Extensions that add two more AA batteries)
• Heavy
• Experimental

The (#) below indicates the maximum number of sub repositories/packages that should exist in the main repo.

Core (1)

Built on a solid foundation and rarely touched, this is a (AA) batteries included core repo. Given it’s minimal functionality, the goal is to provide enough to get up and running without forcing you into massive technical debt (maybe like Express).

Light Packages (10)

A single repo, composed of several sub repos that work in tandem like a package. While all of the packages should work seamlessly together, you could add your own package, or remove a couple and still have the other packages working flawlessly. For example, let’s say your package is a mail server using “mailgun”. Another developer should easily be able to swap out that package for sendgrid, sendinblue or other mail server service, without any conflicts to the other light packages

In essence, think of these sub repos as adding a second set of AA batteries to the core. This is extended functionality — nice to have to but not required.

And of course, always add documentation.

Heavy Packages (aka. Extensions -Unlimited)

Group #1 (Tightly Coupled)
These packages are tightly integrated with the light modules and require all of the light modules to be enabled. These packages work as a full unit, cannot survive on their own, and are meant to add substantial functionality to the core and light modules. Activating a heavy package should allow the developer to plug and play with minimal or no effort. In some cases you could consider group #1 packages to be mini frameworks. A cli should be added here for one click commands.

Group Type #2 (Loosely coupled)
These packages are meant to work independently of group #1 and light packages. They should work flawlessly with the core package. These packages could rewrite a group #1 templating engine package, or change the way an ORM functions.

Experimental
Experimental modules that are exactly that, experimental, meaning they are only for testing. You can compare these modules to a “beta” and “edge” release. While these modules should never break the core — they could break any of the other packages above, so you would use these with caution.

In an open source project, sometimes a feature really doesn’t belong anywhere else, especially if it does not align with the focus of the software build. Having an experimental repo allows side projects to form, that may one day make it to the light or heavy packages.

Minimal Use

Every environment does not have to be a fully secure DevSec environment. When I am collaborating with other developers to unit test or build something very quickly, I generally use the following 5 minute setup:
- Docker (with docker gen, and let’s encrypt behind an nginx reverse proxy)
- GitLab Runner
- Dedicated Box (The Throwaway Server)

This quick setup allows me to build a truly isolated, yet semi-secure development integrated environment with minimal cost — not everything needs to be hosted in the cloud.

Use Standard And Professional Variable Names

What makes sense to you may not make sense to another developer. These are many rules and guides you can find online that guide towards great naming conventions. I generally have one rule when it comes to naming conventions.

Minimize the possibility of confusion. For example a Person class with “get_person()” and “get_person_info()”. Looks like you can get the person’s info with both methods — although I doubt that was the intend of the original developer.

Databases:

Just dump the data into Postgres is definitely NOT the way to approach data storage. After making the decision on whether you are going to use SQL or noSQL, you’ll still need to choose the type of SQL or no SQL database.

When I first started managing databases, I would perform all tasks and functions manually and rarely used any scripts. Not only did I want to better understand the database management process, but I knew it would eventually that practice would help me in the future should I have the desire to choose a managed database provider.

If you understand how database operations work, when you choose a solid managed service provider, you can focus on data management and worry less on whether your data is ACID (Atomic, consistent, isolated, and durable).

Remove Redundant And Unnecessary Code

Sometimes a library you created or imported that you thought you would need is no longer being used. The good thing about Dart is that it implicitly indicates when code is unused. You can also use the “dart analyze” command to run through any issues with your code (Using VS Code).

Testing i.e. Validation and Verification

Using CI/CD is very important to ensure that you are thoroughly testing your code. I use Gitlab to manage much of the process with pipelines. Click here for a quick guide on setting up pipelines. The main reason I use Gitlab as opposed to another tool is that everything is tightly integrated for devops operations.

Interested in the growing Flutter/Dart ecosystem? Join the conversation in our discord community https://discord.gg/xWz8V7W