Key Software Engineering Principles and Practices for High‑Quality Code

1. Details Are Architecture

Good code treats details as part of the overall architecture; writing code without considering its lifecycle misses the engineering dimension of time.

2. Bind Code and Documentation (Self‑Explaining Principle)

Documentation should be close to the code it describes. Use tools like Go's godoc to generate docs from well‑written comments, and keep documentation in the same repository as the code.

3. ETC Value (Easy to Change)

Design decisions should support rapid change; avoid hard‑coded assumptions about data types, storage, or protocols.

4. DRY Principle

Never repeat yourself; extract common logic into reusable functions or interfaces.

5. Orthogonality (Avoid Global Variables)

Modules should be independent; global state creates hidden coupling. Prefer composition over inheritance and use the Dependency Inversion Principle (DIP) to invert control.

6. Reversibility Principle

Design should allow decisions to be undone; avoid committing to immutable choices such as a fixed user‑ID size or a specific database technology.

7. Early Crash

Fail fast and surface errors early; use proper error propagation instead of swallowing errors, and log only when necessary.

8. Avoid Method Chaining

Expose simple, single‑purpose functions rather than deep chained calls that hide complexity.

9. Inheritance Tax (Prefer Composition)

Inheritance creates tight coupling across class hierarchies; composition and interfaces provide more flexible, maintainable designs.

10. Do Not Chain Calls

Write functions that operate on the minimal required data set; avoid passing whole structs when only a few fields are needed.

11. SOLID Principles

Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion form the backbone of clean object‑oriented design.

12. Unix Philosophy Basics

Modules should have simple interfaces, be composable, separate strategy from mechanism, stay concise, be robust, and expose clear contracts.

13. Error Propagation Principle

Use Go's error wrapping (or exceptions in other languages) to carry context up the call stack; panic should be reserved for truly unrecoverable situations.

14. Code Layering

A function should contain only one logical layer; deeper details belong in helper functions.

15. Transparency and Silence

Make code behavior visible through clear naming and minimal logging; avoid noisy logs that drown out real errors.

16. KISS (Keep It Simple Stupid)

Simplicity is not the easiest solution but the most effective; strive for concise, well‑structured designs.

17. Example: Dependency Inversion in Go

package dippackage

type Botton interface {
    TurnOn()
    TurnOff()
}

type UI struct { botton Botton }

func NewUI(b Botton) *UI { return &UI{botton: b} }

func (u *UI) Poll() { u.botton.TurnOn(); u.botton.TurnOff(); u.botton.TurnOn() }

Implementations for different lamps (Java, Python) satisfy the same interface without explicit inheritance, demonstrating DIP.

18. Example: Avoiding Global State

Instead of a shared variable, introduce a manager that serialises access via messages, eliminating race conditions.

19. Conclusion

The article emphasizes that mastering these principles—documentation, composition, error handling, and disciplined logging—helps engineers write code that is easier to review, modify, and scale.