Skip to content
Sparkbit Development Guidelines
General Development Guidelines - Table of contents
General Development Guidelines - Table of contents
(Navigation tip: Each Title is a hyperlink that will lead you to a specific paragraph in the full document)
Table of contents - General Development Guidelines
Topic
ID
Title
Short description
Writing Code
13
WC01
Each language and technology has its own set of guidelines that recommend programming style and practices. Follow these rules instead of not following any rules or inventing custom ones.
WC02
Always use English names for variables, functions, classes etc. and for writing comments.
WC03
The names should reveal intentions. What the variable is for, what the function is doing.
WC04
Good function or class should be responsible for doing just one thing. If it is doing more, then it should be possible to extract a separate function or class out of it.
WC05
A piece of code, i.e. a function or a program, should fail as soon as an unrepairable erroneous condition is encountered.
WC06
All user input should be validated as soon as it enters the system. Input data should be checked for syntactic errors and context-free rule violations.
WC07
Comments can be useful for explaining why a part of code was created, not what it is doing.
WC08
Commented out code should never be committed to the repository. It should be removed.
WC09
When you commit a TODO/FIXME comment always create a new issue in the project issue tracker. A link to the issue should be added to the source code comment.
WC10
Catch an exception only when you want to handle it, to add contextual information or to throw another exception instead.
WC11
Certain tasks an application realizes need to be performed differently depending on the environment. Such tasks shouldn’t be implemented in an environment-specific way.
WC12
Use value wrappers instead of raw types to represent domain values that are constrained or express value and unit.
WC13
Use generic exception handler at top-level of the application to capture any exceptions that haven’t been handled on lower levels.
Writing Unit and Small Integration Tests
9
WU01
Unit and small integration tests should be written by a developer writing code that is being tested. The task should not be considered done until necessary tests are written and are passing.
WU02
Test data used in automated tests must not contain offensive, childish or attempting-to-be-funny words or sentences. Use a neutral language resembling real data.
WU03
Do not copy tests to change a few inputs. Use parameterized tests for similar test cases.
WU04
Test cases should be short. If some field can be set to almost any value and the output will be the same, then the input should be omitted.
WU05
A test should only verify outputs that are important for the specific case, and nothing more (sometimes all outputs are important).
WU06
Tests should not depend on current time, timezone, locale, local resource, machine type, OS etc.
WU07
Unit and small integration tests should not depend on each other.
WU08
Unit and small integration tests should be easy to run by IDE or at least by a single command that is documented.
WU09
Write code that is easy to test. Refactor code if it is hard to test or additional tests are required.
Solution Architecture
8
SA01
A developer should add functionality when it is needed, not when it is foreseen that it may be needed in the future. Do not overengineer the system architecture by making it resilient to events that will most likely never happen.
SA02
Using niche over mainstream is allowed only if mainstream is lacking required capabilities making it impossible or very inconvenient to use.
SA03
Sparkbit has experience working with the following solutions: Keycloak, Auth0, “Sign in with Google”.
SA04
In public networks (ie. Internet) never send secrets such as passwords or authorization tokens using unencrypted connections. In private, secure networks it is allowed.
SA05
This rule applies also to local and development secrets, not only production ones.
SA06
Secrets should not be embedded in built applications such as Docker images, jar files, pip packages etc. Instead they should be provided at runtime.
SA07
Take into account: Business requirements, Technical limitations, Client ease of use, e2e tests needs.
SA08
All API error responses should have the same data type and format, and should be parseable.
Development Process
6
DP01
Having consistent commit message format makes it easier to use git history related tools and getting information about each commit.
DP02
Every commit related to an issue should have a message starting with the issue number.
DP03
To override configuration defaults stored in a git repository use local configuration files added to .gitignore.
DP04
Code should not be merged into the main repository branch without code review.
DP05
A linter, a formatter, and possibly other static analysis tools, if available for used programming language, must be used to enforce a consistent coding style and detect simple errors.
DP06
Code must not be merged into the main repository branch without passing automated checks and tests performed by centralized CI/CD pipelines.
Operations
2
OP01
Deployments, database migrations and other non-trivial, repetitive tasks should be automated.
OP02
Every time an error/unhandled exception occurs in an environment that is expected to be stable an automated notification should be sent to appropriate receivers to make sure that it doesn’t go unnoticed.
Want to print your doc?
This is not the way.
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.