152 lines
3.7 KiB
Text
152 lines
3.7 KiB
Text
-----------
|
|
Style Guide
|
|
-----------
|
|
|
|
This document outlines repo conventions, code style, etc.
|
|
|
|
|
|
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]'.
|
|
|
|
// Final commit
|
|
commit SOME HASH
|
|
Author: Your Name <your@email>
|
|
|
|
finish 034
|
|
|
|
// Intermediate commits
|
|
commit SOME HASH
|
|
Author: Your Name <your@email>
|
|
|
|
Blah blah blah
|
|
|
|
// Starting commit
|
|
commit SOME HASH
|
|
Author: Your Name <your@email>
|
|
|
|
start 034
|
|
|
|
|
|
Writing Code
|
|
------------
|
|
|
|
Generally, I don't care what style of code is used. It's
|
|
more important that you stay in line with the local style
|
|
of the file you're in.
|
|
|
|
Things I actually care about:
|
|
|
|
- Don't be clever. Write code that does the job;
|
|
nothing more, nothing less.
|
|
|
|
- Comment your code. I very much disagree with the
|
|
premise that code is self-documenting. Take a step
|
|
back and write a comment (with your name) that
|
|
explains *why* you're doing *what* you're doing.
|
|
Please try to stick to this format:
|
|
@note, @todo, @temp, @allocates, @leak
|
|
|
|
- Descriptive names. In general, it's fine to use short
|
|
names for local variables. However, you should
|
|
almost always opt for longer, more descriptive names
|
|
in every other context.
|
|
|
|
|
|
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";
|
|
}
|
|
|
|
|
|
Bindings
|
|
--------
|
|
|
|
Binding modules should default to static linking and take
|
|
an optional '#module_parameter' to link dynamically.
|
|
Libraries should be pinned to a specific version, and all
|
|
binaries (.dll, .dylib, etc.) *must* be checked into
|
|
source control. If possible, use the release build of the
|
|
library that includes debug information.
|
|
|
|
Bindings should stay as close as possible to the original
|
|
library. To jai-ify the bindings, create a submodule
|
|
called 'wrapper' that import and wraps the api.
|
|
|
|
See: 'thirdparty/raylib' for example bindings.
|
|
|
|
|
|
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.
|
|
|