Diosix style guide

This guide defines the standards for contributing to the Diosix project, ensuring consistency across both documentation and the codebase. All contributors must follow these guidelines to maintain the project’s high standard of quality.

Technical documentation style

Diosix documentation is written for a technical audience and prioritizes clarity, precision, and professional prose. All documentation must be comprehensive while remaining as concise as possible.

Voice and tone

Maintain a professional and direct tone that avoids marketing hype, jargon, and unnecessary waffle. Every sentence should provide tangible value to the reader. Use the active voice and present tense whenever possible, such as “The hypervisor handles the request” rather than “The request is being handled.” Strive for conciseness and be as detailed as necessary to explain complex designs.

Abbreviations and terminology

Spell out every abbreviation on its first use within a given page, followed by the abbreviation in brackets. For example, use “Virtual Machine (VM)” or “Supervisor Binary Interface (SBI)” for the first mention. For all subsequent mentions on that same page, use only the abbreviation.

Structure and formatting

Use bulleted lists only for non-sequential items and numbered lists strictly for multi-step procedures. To maintain readability in terminal-based environments, wrap all text at approximately 80 characters.

Coding style

Diosix follows idiomatic Zig conventions to ensure the codebase remains accessible and maintainable for the wider community.

Naming conventions

For functions and variables, use camelCase. Types, structs, and enums must use PascalCase. Constants should use snake_case or SCREAMING_SNAKE_CASE depending on their scope and intended usage. All source files must use snake_case filenames.

Comments and documentation

All comments must follow standard sentence structure, beginning with a capital letter and ending with a period. The code should be largely self-documenting; use comments to explain the “why” behind a design decision rather than the “what,” unless the logic is particularly intricate. Maintain a professional tone and avoid technical jargon where a simpler explanation suffices.

Idiomatic Zig usage

Be explicit about memory management and allocations, and consistently use errdefer to ensure proper resource cleanup during failures. Use descriptive error sets and avoid swallowing errors. All code must be formatted using zig fmt before it is submitted for review.