147 lines
4 KiB
Text
147 lines
4 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 (bonus points if your initials are "JC"). 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
|
|
|
|
|
|
Communication
|
|
-------------
|
|
|
|
If direction is needed, create a single commit with an
|
|
entry in 'INBOX' at the top of that person's section; the
|
|
commit message should roughly say 'message for [name]'.
|
|
|
|
If an immediate response is needed, opt for direct
|
|
messages instead.
|
|
|
|
Use this as a base plate to write new messages:
|
|
|
|
[ToName]
|
|
05.25.25 ToName // This is a response
|
|
Excepteur sint occaecat cupidatat non proident,
|
|
sunt in culpa qui officia deserunt mollit anim
|
|
id est laborum.
|
|
05.22.25 FromName // This is a question
|
|
Lorem ipsum dolor sit amet, consectetur
|
|
adipisicing elit, sed do eiusmod tempor
|
|
incididunt ut labore et dolore magna aliqua.
|
|
|
|
You should check your inbox *every time* you pull.
|
|
|
|
|
|
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.
|
|
Sticking to this format makes my life easier:
|
|
@note(name), @todo, @temp, etc.
|
|
|
|
- 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.
|
|
|
|
- Documentation will get auto generated if the comments
|
|
start with '///'. General format is: '/// Foo ...'
|
|
where 'Foo' is a procedure, type, whatever. To get
|
|
examples to show up, indent them more than the other
|
|
text. To prevent something from being documented,
|
|
attach '@jc.nodocs' to it.
|
|
|
|
|
|
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"; // @future
|
|
|
|
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'.
|
|
|
|
#import "jc"; // the base module can be unnamed
|
|
math :: #import "jc/math";
|
|
|
|
|
|
Memory Management
|
|
-----------------
|
|
|
|
If a type needs dynamically allocated memory to function,
|
|
it should always assume the memory came from an arena
|
|
allocator. This means it is the responsibility of the
|
|
arena to free the memory, not the data type.
|
|
|
|
In other words:
|
|
|
|
Do *not* add procedures that 'free' or 'delete' the memory
|
|
allocated by the data type.
|
|
|
|
Instead, add procedures that 'reset' the data type,
|
|
allowing its memory to be reused.
|
|
|
|
|
|
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 a 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.
|
|
|