Skip to content
General Development Guidelines - Table of contents
General Development Guidelines
General Development Guidelines
Writing Code
Follow industry standard coding conventions
ID
WC01
Description
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.
Rationale
Coding conventions improve code readability, allowing developers to quickly understand it. It makes code review and maintenance easier. Industry standard coding conventions for a given language or technology are a result of shared experience of many, many developers. They are well known by the developer community and supported by IDEs and tools that automatically enforce application of the conventions. Inventing custom coding conventions, different from the standard ones, loses a benefit of familiarity and introduces the cost of maintenance and developer education.
Each project should clearly document which coding conventions it follows.
Exceptions
Having coding conventions is most beneficial during code maintenance. In PoCs effort is concentrated on delivering a working prototype as quickly as possible and all time investments that will pay off only during maintenance should be avoided. Because of that this rule might not be enforced for PoCs but should still be followed as long as it doesn’t require additional time.
Links
Use English for names and comments in source code
ID
WC02
Description
Always use English names for variables, functions, classes etc. and for writing comments. Words in other languages can be used as test data in automated tests in order to verify if software correctly handles non-english characters.
Rationale
We’re working in an international environment cooperating with foreign clients and team members.
Exceptions
None
Use meaningful names for methods, classes, functions etc.
ID
WC03
Description
The names should reveal intentions. What the variable is for, what the function is doing. Good function name can be long, but it should let other developers (and you in the future) understand the function goal without the need to analyze the code. Long, meaningful name is better than a short one, which doesn’t describe the function.
Rationale
Meaningful names make the code easier to read and understand and develop further in the future.
Exceptions
Variables with a really small scope, like an index in a small loop or an element of a list in a small mapping function.
Links
Examples
Bad names:
Good names:
Design functions and classes that are simple and do just one thing
ID
WC04
Description
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.
Rationale
Functions and classes that do just one thing make the whole code easier to understand and make it easier to find a place responsible for a specific feature. They are also easier to test.
Exceptions
In PoCs it is possible to skip this rule. It should be kept when writing new code, but not necessarily when it needs to be rapidly changed, as happens in PoCs.
Links
Follow the Fail Fast principle
ID
WC05
Description
A piece of code, i.e. a function or a program, should fail as soon as an unrepairable erroneous condition is encountered. The code should check for erroneous conditions like wrong parameter values, unmet pre- or post-conditions, violated invariants, etc. and report them by for example throwing an exception or returning an error code. This rule takes precedence over the once popular but currently mostly discouraged “single exit point” rule
Rationale
It is better to have a crashed program with a clear failure cause than a misbehaving program with undetected problems. Having identified preconditions, postconditions and invariants makes development easier by narrowing down the range of data that a method should support. A function that checks its preconditions and fails fast on errors is much clearer to read and understand as it for example avoids deeply nested code.
Exceptions
None
Links
Validate user input early and defensively
ID
WC06
Description
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. Validations that depend on the internal state of the system (eg. uniqueness checks) can be done deeper in the system if the validation layer doesn’t have access to that state. This rule is an extension of the “Follow the Fail Fast principle” rule.
Rationale
Validating input early allows to treat data as “safe” during the subsequent processing. This makes the code cleaner and easier to write.
Exceptions
This rule can be skipped for PoC projects.
Write comments when the code needs context, not when the code is messy
ID
WC07
Description
Comments can be useful for explaining why a part of code was created, not what it is doing. Add comments when a part of code was created for some not obvious reason, eg. to support a behavior of a particular browser, or an external library etc. Add links to external sources if they can help understand the context. Don't add comments when the code is complicated and written in an unstructured way, improve the code instead.
Rationale
It’s less time consuming and less error-prone to debug and/or modify a self-explanatory code than an obscure code that is explained in an adjacent comment. Additionally, explanations provided in comments have a tendency to get outdated, as updating them is technically not required to alter behavior of the application. When they get outdated, they turn from helpful to harmful.
Exceptions
None
Don't commit commented out code
ID
WC08
Description
Commented out code should never be committed to the repository. It should be removed. In case it is needed again in the future it can always be found in git history.
Rationale
Commented code raises questions on why it was commented out and if it should remain that way. Everybody looking at this piece of commented out code will unnecessarily spend a moment reading this code. It just introduces confusion with no real benefits.
Exceptions
None
Links
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.