How to structure
...
your Component Translator projects is critical to fast, scalable development. Before taking a look at the details of Lua,
...
it’s good to understand how to organize
...
functions and modules in the Translator
...
Each component can be broken down into three parts that form a pyramid
Top: snowflake
These are the specific mappings and transformations
Middle: processes
Functions that do things
Bottom: systems
Interacting with external entities
...
Next point is how to organically write code so that it follows this three part pyramid structure
...
These are the three most important things to keep in mind when developing Lua code, and if you follow these, you will almost automatically follow our best practices for how component Translators should be structured (this is from IUC 2023 presentation on Interface Design)
Naming convention
Describe what the function does
Include interacting system
Configuration management
Avoid hardcoding
Custom fields and environment variables
Centralize configurations
Error handling
Log each breakpoint
Capture errors at breakpoints
...
Local vs. using a library
Referencing the below diagram, anything on the far right is a good candidate to be a library
...
.
Each Translator project is made up of different types of files. Knowing how those files relate to each other and using the concept of separation of concerns is key to determining how to structure your projects.
In general, what files make up a Translator project?
...
| Expand | ||
|---|---|---|
| ||
Main.lua is called when you start a component. Every other file in your project is called from main.lua. Best practice is to keep this like a table of contents, as small and easy to read as possible. |
| Expand | ||
|---|---|---|
| ||
Local files are used for creating functions that are specific to a single component. They help separate concerns ensuring your project remains easy to read and maintain. Keep local files small. Give them descriptive names. |
| Expand | ||
|---|---|---|
| ||
Every project has a config.json file you can use to create Custom fields. This is where you should store component or environment-specific configurations. For more details, see Configuration Management. |
| Expand | ||
|---|---|---|
| ||
Libraries contain common code that can be used by multiple components. A key strategy in creating component templates and speeding up interface development. In general, if you use a function more than one interface, it belongs in a library. If you have any libraries added to a project, a .gitmodules file automatically updates to list any referenced libraries. |
| Expand | ||
|---|---|---|
| ||
The Samples folder holds all of the sample messages you need to use to develop and test your interfaces. |