D 2019-08-24T00:11:24.406
L rules
N text/x-markdown
U lexi
W 2104
# rules
this page is an evolving list of the libk project's official rules.
## coding rules
1. when in doubt, ask yourself, "is this better than glibc?"
2. always include a block comment at the top source files you contribute that includes the file name, the name of the function it defnes (if any), your name/handle, and a brief outline of the file's purpose. try to follow the pattern of existing files.
3. create one file per function. if you add extra supporting functions to a file, they must not be included in the header, and must be marked `static` to prevent them from being exported. helper functions do not need to follow any namespacing convention, as they are not exported.
4. in your C, do not rely on any headers that are not defined within libk itself.
5. assembly code should compile under yasm and nasm. intel syntax is required, and inline assembly in C files is forbidden as it creates a maintenance nightmare and is non-standard.
6. write as little assembly as possible. remember that every line of assembly you write is another line . assembly should only be used for those tasks that absolutely cannot be accomplished with C.
7. comment your assembly very thoroughly. nearly every line should have a paragraph explaining its purpose in context, to aid porting and make the libk source useful as a tool for understanding how systems function at a low level.
8. try to maintain clean abstractions, but keep in mind that abstraction should always serve a material purpose. never mix layers of abstractions, as this can make it hard to maintain clean separation between OS-specific code and general-purpose code.
9. do not create new modules without first consulting the rest of the libk team.
## community rules
1. for the time being, the project maintainer is the final arbiter over both technical and social issues. however, if a solid core leadership team can be established, it may be in the project's best interest to transition from autocracy to oligarchy.
the team is currently still small enough that no further community rulemaking has yet been necessary.
Z 3fcdedf1f243b460f3cb7670f3fb9914