diff --git a/README b/README index 0151a50..475944c 100644 --- a/README +++ b/README @@ -27,6 +27,8 @@ How If you'd like to learn more about *what* a specific module does, take a look at its 'module.jai' file. +If you'd like to contribute, read STYLEGUIDE. + Why --- diff --git a/STYLEGUIDE b/STYLEGUIDE new file mode 100644 index 0000000..98e39c1 --- /dev/null +++ b/STYLEGUIDE @@ -0,0 +1,113 @@ +----------- +Style Guide +----------- + +This document serves as a loose style guide for the repo. +Generally, you should write code that follows the local +style of the file you're in, however, there are a few +conventions to keep in mind. + + +Getting Paid +------------ + +To pick up tasks, find something in TODO and message me +your rate. If accepted, create a single commit moving it +from the 'UP NEXT' section to your 'IN PROGRESS' section; +the commit message should only say 'start [id]'. + +Once the work is done (use as many commits as you'd like), +create another commit moving the task from your 'IN +PROGRESS' section to the 'DONE' section; the commit +message should only say 'finish [id]'. + + // Starting commit + commit SOME HASH + Author: Your Name + + start 034 + + // Intermediate commits + commit SOME HASH + Author: Your Name + + Blah blah blah + + // Final commit + commit SOME HASH + Author: Your Name + + finish 034 + + +Imports +------- + +When importing modules that ship with the compiler, ALWAYS +namespace them. The eventual goal of this repo is to be a +standalone library that doesn't rely on compiler-shipped +modules (unless absolutely required). + + basic :: #import "Basic"; + +When importing 'jc' modules, ALWAYS namespace them and use +absolute import paths. '#import,file' does not function +the same as '#import' and causes issues when mixed +with '#load'. '_run_all_tests.jai' is an exception to +this rule. + + math :: #import "jc/math"; + + +Modules +------- + +Modules should *generally* have a small scope and not be +nested unless it allows better organization. Files within +modules are not intended to be imported directly; it is +the job of 'module.jai' to '#load' and '#scope_export' +module files. + +When authoring a new module, use this as a base plate: + + // Within module_name/module.jai + #module_parameters(RUN_TESTS := false); // Should be the last parameter if others are required + + #load "file_a.jai"; + #load "file_b.jai"; + + #if RUN_TESTS { + test :: #import "jc/test"; + } + + +OS-Specific Code +---------------- + +When writing code for a specific operating system, use a +switch statement over multiple files. + + // Top-level scope of file: + #if OS == { + case .WINDOWS; + case .MACOS; + case .LINUX; + case; #assert false, "unimplemented platform"; + } + +If multiple files are required, use these file suffixes +and conditionally '#load' them based on 'OS'. + + Windows: '_win.jai' + Mac: '_mac.jai' + Linux: '_linux.jai' + WASM: '_wasm.jai' + + +Architecture-Specific Code +-------------------------- + +When writing code for a specific architecture, use +the 'jc/arch' module. NEVER create a new file unless +absolutely needed. +