Project Development
Project Development Principles
Rules for compiler development, language design, native interoperability, builds, tests, and documentation.
Development rules
- Keep source clear. Avoid comments that merely restate obvious code behavior and avoid unnecessary explanatory noise.
- Publish only used and approved documentation. Proposed ideas must be labelled as proposals; obsolete notes must not sit beside the active specification as if they were current rules.
- No OOP model in Raz. Raz and its compiler development do not use classes or class-dependent methods as a language or compiler architecture.
- Prefer direct implementations where practical. Use the native capabilities of the target/toolchain when that avoids unnecessary abstraction or overhead, while keeping the resulting behavior explicit in the language contract.
- Keep compiler and library responsibilities separate. The compiler parses, validates, and translates source. Standard-library modules complement programs; Raz library source is compiled by the selected compiler, while native C/C++ headers remain native dependencies.
- Remove superseded development paths. Old generation or legacy files should not remain active dependencies after their replacement is established.
Build policy
Ordinary native builds use GNU C++ and the flags in the
repository-root options file. Static linking and
production stripping are the current defaults; special compiler or
flag overrides must be explicit.
Testing policy
- Compile all Raz test sources and preserve their generated C++ next to the source files for manual review.
- A positive test passes when Raz compilation succeeds and a non-empty C++ output is generated; a negative test passes when the Raz compiler rejects the source.
- Continue processing the manifest after individual failures and report the final aggregate result.
- Do not make compiling or executing every generated C++ file part of the default test runner. Add native compilation or execution only for cases that require it.
Memory safety direction
Memory safety is a design goal. Raw pointers are not intended to be
required for ordinary Raz code, but the current implementation
permits a restricted char* form inside
unsafe for low-level and compiler-development needs.
This is a current limitation, not a complete safety guarantee.
Documentation policy
The active reference manual is authored in HTML with a shared stylesheet, navigation, and search. Each language feature should have a concise entry in the relevant index and a dedicated reference page when its behavior needs more detail. A design inspiration is not a specification: the Raz behavior must be defined separately.