diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md deleted file mode 100644 index 30a3c27..0000000 --- a/CODING_STANDARDS.md +++ /dev/null @@ -1,100 +0,0 @@ -# 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)