Building your first, second, or even twentieth application can be tricky: How am I going to design my Data Model, what interface do I need for my users, what kind of actions do I need, etc. Especially when you're working on it with others. You need a proper plan and set of rules to avoid chaos, jeopardizing the project.
After reading this article, you'll know:
- Why it's necessary to follow conventions.
- Which conventions to follow.
Keeping an overview
What would happen if everybody is building in the same application, not minding the work of other developers, each following his or her own rules? Chaos.
Without alignment, each developer uses different rules when it comes to developing an application. Following conventions as a team ensures a clear overview of the app.
- Language: Which language is used for the application, used in Models, Actions, etc.
- Notation: How are names and descriptions written in Models, Properties, Relations, etc.
- Model Normalization: On which levels are Models divided when creating a larger Data Models.
- Building actions and pages: Reusing certain parts instead of rebuilding the same logic over and over.
What rules to follow?
We're not the ones telling you what to do and what not. Actually, you're free to do whatever you want and ignore all rules.
But if you decide to restore some order in your application, these are some good starters we recommend:
English: As the main language of the Betty Blocks platform is English, designing your application with English naming is recommended.
Singular CamelCase: Give your models a singular name, as the model represents a single object. When using the model in your application, the platform automatically uses the plural name if necessary.
Instead of using spaces when a name consists of multiple words, use CamelCase. Each word in the name starts with a capital. Example:
Singular snake_case: Give your properties a singular name. If a plural name is required, consider using a relation to another model. When including a space, as it consists of multiple words, use underscores (
_ ) instead. Example:
Date/Datetime: Often describing a moment when something occurred. Append with
Checkbox: Often describing a state in which something is in. Prepend with
snake_case: When including a space, as it consists of multiple words, use underscores (
_ ) instead. Example:
Belongs to: Singular. Example:
Invoice belongs to customer.
Has many: Plural. Example:
Invoice has many invoice_lines.
Has and belongs to many: Plural. Examples:
User has and belongs to many roles and
Role has and belongs to many users.
Separate actions: Prevent hard-to-maintain actions filled to the brim with events. Split huge actions into multiple flows, each consisting of no more than 10 events, the one starting the other. This is easier to test, edit and maintain.
Routing: Use the same format of routing in your webpages throughout your entire application. This means the paths should consist of the same buildup.
GET /products : Overview of all products.
GET /products/:id : Detailpage of product.
GET /products/new : Page with form to add new product.
POST /products : Endpoint with action to create new product.
POST /product/:id : Endpoint with action to change exisiting product.
POST /product/:id/delete : Endpoint with action to delete exisiting product.
GET/POST/PUT /api/v1/products : Using endpoints as a custom API should be preceded with
/api/ and a version number.
These were some conventions we use on a daily basis in our own projects. Feel free to follow them as-is, change them to your liking or ignore them and create your own rules.
In the end, the most important rule is: BE CONSISTENT.