-
Notifications
You must be signed in to change notification settings - Fork 0
Coding Guidelines
This document describes the coding guidelines for Ostin project. All the guidelines efficiently are requirements unless noted otherwise, and as requirements they have to be met in order for anyone to be able to take part in the project (meaning both patches and commits).
Ostin project is the assembly-only project. No other languages are allowed, including assembly code generated by means of HLL (and not so HLL) compilers or as a result of disassembling the code of mentioned compilers. Since in many cases there is no way to tell, final decision on code acceptance is always up to project maintainers.
Ostin project uses FASM as its primary assembler. No code for any other assembler is allowed.
For the simplicity of this document, all sub-programs are named procedures, no matter if they return any result or not.
Right margin should be set to 120 characters.
Each label or instruction has to be properly aligned.
There are three types of labels we use:
- anonymous labels (those named @@) should be indented to column 4
- local labels (those having names beginning with a dot) should be indented to column 2
- global labels (all other labels) should not be indented at all (positioned at column 0).
Instruction mnemonics should be indented to column 8. Instruction operands should be indented to column 16.
Inline comments (those appearing in the middle of procedure code) should be positioned in two possible places:
- on a separate line indented to column 8
- on the same line with assembly instruction right after it.
There are also special comments used to describe (sub-)procedures. They should never be indented (positioned at column 0).
Each label or instruction has to be placed on a separate line unless noted otherwise.
It is good to add single empty lines between code and/or comment blocks having distinct meaning you might want to emphasize.
Each label (no matter its type) should be preceded by an empty line.
In case of anonymous labels, instruction or comment immediately following it should be placed on the same line according to indentation rules.
If there is more than one instruction operand so that they are separated with commas, there should be a single space after each comma before next operand.
Each operation token, should be separated from both operands with a single space character. Exception is unary minus which should go right before its operand, with no spacing.
If there is a need to split expression into two or more lines, operation token should always stay in the end of current line and never in the beginning of next line.
It is good to use round braces to group expressions with operations having ambiguous precedence (for example, while mixing multiplication and division with binary operations) to make the code clear and help novice developers better understand it.
If there is a type casting operator before memory location operand, it should go right before the opening square brace, with no spacing.
If there is a prefix instruction (like rep) used, next instruction could reside on the same line (with mnemonic aligned to column 16), but only if it doesn't take any operands; otherwise, prefix instruction should reside on a separate line preceding next instruction.
Comment text should be separated from comment marker with at least one space character.
If comment is placed on the same line with assembly instruction, comment marker should be separated from instruction by a single space character.
All the identifiers should have meaningful names.
Any identifier name could contain one or more prefixes (or namespaces) which specify its affiliation with some concrete kernel module. They should then be separated from each other and from the identifier itself with dots. Identifiers which are meant to be private to some specific assembly unit (and not referenced from other units) should refer _ (underscore) namespace as their last one.
...
...
...
...
...
...
Expressions should be kept as simple and readable as possible. Whenever you can, define helper constants and utilize them instead of "magic numbers".