126 lines
5.0 KiB
Markdown
126 lines
5.0 KiB
Markdown
# Global coding preferences
|
|
|
|
Apply these preferences across all projects unless repository-specific
|
|
instructions override them.
|
|
|
|
## General philosophy
|
|
|
|
I prefer clean, readable, maintainable code with strong structural discipline,
|
|
inspired by 42-style constraints but adapted pragmatically to each language,
|
|
framework, and project.
|
|
|
|
These rules are important, but they are not absolute dogma:
|
|
- apply them by default
|
|
- report clearly when code does not follow them
|
|
- if a deviation is justified, keep it and explain why
|
|
- if a deviation is not clearly justified, ask whether it should be kept or fixed
|
|
|
|
## Design principles
|
|
|
|
- Prefer simple, readable, maintainable code over clever or overly compact code.
|
|
- Each function, method, or equivalent unit should have one clear responsibility.
|
|
- Preserve existing behavior unless explicitly asked to change it.
|
|
- Avoid unrelated changes during a fix or refactor.
|
|
- Keep modifications scoped and intentional.
|
|
|
|
## Function and method size
|
|
|
|
- Prefer keeping the core logic of a function or method within 25 useful lines.
|
|
- Empty lines do not count toward this limit.
|
|
- Multi-line wrapped statements count as one logical instruction for this rule.
|
|
- Error handling may extend the total size when necessary, but the main logic
|
|
should remain compact and easy to understand.
|
|
- If a unit becomes too large, split it into small helpers.
|
|
- Use private/internal/file-local helpers when the language supports them.
|
|
|
|
## Line length
|
|
|
|
- Prefer a maximum of 80 characters per line when reasonably possible.
|
|
- If a line is too long, split it cleanly for readability.
|
|
- Long calls, conditions, and expressions should be formatted clearly.
|
|
|
|
## Parameters
|
|
|
|
- Prefer no more than 5 parameters per function or method.
|
|
- If more inputs are needed, group them into a meaningful structure adapted
|
|
to the language, such as an object, record, struct, dataclass, DTO,
|
|
config object, or equivalent.
|
|
|
|
## Local variables
|
|
|
|
- Prefer no more than 5 local variables per function or method.
|
|
- If more local state is needed, consider:
|
|
- splitting the logic
|
|
- extracting a helper
|
|
- introducing a dedicated small structure adapted to the language
|
|
|
|
## Shared and global state
|
|
|
|
- Global state is discouraged.
|
|
- Prefer explicit data flow through parameters, return values, objects,
|
|
context structures, dependency injection, or another justified mechanism.
|
|
- If shared or global state is used, mention it explicitly and justify it.
|
|
|
|
## Comments and documentation
|
|
|
|
- Functions and methods should be documented when their purpose, parameters,
|
|
return value, or intent are not immediately obvious.
|
|
- The comment should help explain intent and usage, not restate the code line by line.
|
|
- Apply the documentation style that fits the language and project conventions
|
|
(docstring, block comment, JSDoc, Doxygen, XML docs, etc.).
|
|
- Internal/private helpers are not exempt if their role is unclear.
|
|
|
|
## Readability
|
|
|
|
- Use explicit, consistent, and meaningful names.
|
|
- Prefer straightforward control flow.
|
|
- Simplify or extract complex conditions.
|
|
- Avoid hidden side effects unless clearly necessary.
|
|
- Prefer code that is easy to review, test, and modify.
|
|
|
|
## Refactoring and modifications
|
|
|
|
- During refactoring, prioritize:
|
|
1. safety
|
|
2. readability
|
|
3. consistency with the project
|
|
- Keep behavior unchanged unless explicitly asked otherwise.
|
|
- After modifying a function, feature, or behavior, verify that no residue from
|
|
the previous implementation remains.
|
|
- Remove obsolete code, dead branches, unused helpers, stale flags, outdated
|
|
comments, legacy conditions, and old-version leftovers when they are no longer needed.
|
|
- If something from the previous implementation is intentionally retained,
|
|
explain why.
|
|
|
|
## Handling deviations from the standard
|
|
|
|
- Treat these rules as strong preferences, not rigid mechanical laws.
|
|
- If existing code is outside the standard, report it clearly.
|
|
- If the deviation is minor and acceptable, mention it briefly.
|
|
- If the deviation is significant and not obviously justified, ask whether to:
|
|
- keep the deviation
|
|
- or refactor toward compliance
|
|
- If a deviation is clearly justified by language constraints, framework style,
|
|
performance needs, safety requirements, or project architecture, keep it and explain it.
|
|
|
|
## Language adaptation
|
|
|
|
- Adapt these rules to the language and ecosystem instead of applying C/C++
|
|
terminology blindly.
|
|
- Interpret "function" broadly as the relevant unit of logic:
|
|
function, method, procedure, hook, handler, endpoint, callback, class method, etc.
|
|
- Interpret "structure" broadly as any suitable grouping construct:
|
|
struct, object, class, record, dataclass, DTO, tuple wrapper, options object,
|
|
config object, context object, or equivalent.
|
|
|
|
## Expected workflow after code changes
|
|
|
|
After making changes, when applicable:
|
|
1. run relevant tests
|
|
2. run lint, format, build, and type-check steps if available
|
|
3. report what was verified
|
|
4. report what could not be verified
|
|
5. summarize remaining risks or uncertainties
|
|
6. mention any remaining deviation from these preferences
|
|
7. confirm whether old implementation residue remains or has been removed
|