101 lines
3.7 KiB
Markdown
101 lines
3.7 KiB
Markdown
# Coding Standards
|
|
|
|
These rules apply to every file in this repo , for humans and agents alike.
|
|
|
|
## General rules
|
|
|
|
1. Follow standard conventions.
|
|
2. Keep it simple stupid. Simpler is always better. Reduce complexity as much as possible.
|
|
3. Boy scout rule. Leave the campground cleaner than you found it.
|
|
4. Always find root cause. Always look for the root cause of a problem.
|
|
|
|
## Design rules
|
|
|
|
1. Keep configurable data at high levels.
|
|
2. Prefer polymorphism to if/else or switch/case.
|
|
3. Separate multi-threading code.
|
|
4. Prevent over-configurability.
|
|
5. Use dependency injection.
|
|
6. Follow Law of Demeter. A class should know only its direct dependencies.
|
|
|
|
## Understandability tips
|
|
|
|
1. Be consistent. If you do something a certain way, do all similar things in the same way.
|
|
2. Use explanatory variables.
|
|
3. Encapsulate boundary conditions. Boundary conditions are hard to keep track of. Put the processing for them in one place.
|
|
4. Prefer dedicated value objects to primitive types.
|
|
5. Avoid logical dependency. Don't write methods which work correctly only depending on something else in the same class.
|
|
6. Avoid negative conditionals.
|
|
|
|
## Names rules
|
|
|
|
1. Choose descriptive and unambiguous names.
|
|
2. Make meaningful distinctions.
|
|
3. Use pronounceable names.
|
|
4. Use searchable names.
|
|
5. Replace magic numbers with named constants.
|
|
6. Avoid encodings. Don't append prefixes or type information.
|
|
|
|
## Functions rules
|
|
|
|
1. Small.
|
|
2. Do one thing.
|
|
3. Use descriptive names.
|
|
4. Prefer fewer arguments.
|
|
5. Have no side effects.
|
|
6. Don't use flag arguments. Split the method into several independent methods that can be called from the client without the flag.
|
|
|
|
## Comments rules
|
|
|
|
1. No comments in the codebase. This covers Go, TypeScript/Vue, HTML templates and config files (YAML, TOML, `.env.example`, `.gitattributes`, …).
|
|
2. Explain yourself in code instead: descriptive names, small functions, named constants, explanatory variables.
|
|
3. The only exceptions are tool directives the code needs to work, such as `//go:build` and `//go:embed`.
|
|
4. Don't comment out code; just remove it.
|
|
5. Prose belongs in `docs/` and `README.md`, not in source files.
|
|
|
|
## Source code structure
|
|
|
|
1. Separate concepts vertically.
|
|
2. Related code should appear vertically dense.
|
|
3. Declare variables close to their usage.
|
|
4. Dependent functions should be close.
|
|
5. Similar functions should be close.
|
|
6. Place functions in the downward direction (caller above callee).
|
|
7. Keep lines short.
|
|
8. Don't use horizontal alignment.
|
|
9. Use white space to associate related things and disassociate weakly related ones.
|
|
10. Don't break indentation.
|
|
|
|
## Objects and data structures
|
|
|
|
1. Hide internal structure.
|
|
2. Prefer data structures when there's no behavior to attach.
|
|
3. Avoid hybrid structures (half object, half data).
|
|
4. Keep classes small.
|
|
5. Each class should do one thing.
|
|
6. Keep the number of instance variables small.
|
|
7. Base classes should know nothing about their derivatives.
|
|
8. Prefer many small functions over one function with a parameter that selects behavior.
|
|
9. Prefer non-static methods to static methods.
|
|
|
|
## Tests
|
|
|
|
1. One assert per test.
|
|
2. Readable.
|
|
3. Fast.
|
|
4. Independent.
|
|
5. Repeatable.
|
|
|
|
## Code smells to watch for
|
|
|
|
1. **Rigidity** — the software is difficult to change; a small change causes a cascade of subsequent changes.
|
|
2. **Fragility** — the software breaks in many places due to a single change.
|
|
3. **Immobility** — you cannot reuse parts of the code in other projects because of the risk and effort involved.
|
|
4. **Needless complexity**.
|
|
5. **Needless repetition**.
|
|
6. **Opacity** — the code is hard to understand.
|
|
|
|
## Credits
|
|
|
|
Thanks to [@wojtekluwojteklu/clean_code.md](https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29)
|