Software Engineering Principles

Core principles and preferences for code style, documentation, and development workflow.

Code Style and Patterns

• Avoid unnecessary comments: Code should be self-documenting. Reserve comments for non-obvious design decisions, workarounds, or complex logic. Avoid comments that restate what the code obviously does.

• Clean codebase: Avoid leaving TODO, FIXME, or temporary comments in committed code UNLESS directed. Either implement the feature, create an issue, or remove the comment. Ignore existing ones.

• Self-documenting code: Prefer clear naming and structure over explanatory comments. Method, class, and member documentation should use language/stack best practices. Don't add useless inline comments next to statements UNLESS they explain confusing or complex behaviour.

Documentation

• Concise and useful: Documentation should be informative but not verbose. READMEs should focus on essential information without unnecessary elaboration.

• Structure over verbosity: Prefer well-organized, scannable documentation with clear headings over long paragraphs. Use short examples to illustrate concepts.