Initial version of "rules"
1 +# rules 2 +this page is an evolving list of the libk project's official rules. 3 + 4 +## coding rules 5 +1. when in doubt, ask yourself, "is this better than glibc?" 6 +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. 7 +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. 8 +4. in your C, do not rely on any headers that are not defined within libk itself. 9 +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. 10 +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. 11 +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. 12 +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. 13 +9. do not create new modules without first consulting the rest of the libk team. 14 + 15 +## community rules 16 +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. 17 + 18 +the team is currently still small enough that no further community rulemaking has yet been necessary.