mirror of
https://github.com/SashLilac/cambridge.git
synced 2024-12-22 12:19:01 -06:00
Added conventions for code submission / review.
Also, coding conventions didn't deserve to go first, so I reordered the sections a little bit.
This commit is contained in:
Joe Zeng
GitHub
parent
209e60e82e
commit
5131061e42
134
CONTRIBUTING.md
134
CONTRIBUTING.md
@ -1,47 +1,3 @@
|
||||
Coding conventions
|
||||
------------------
|
||||
|
||||
* Use tabs to indent, spaces to align.
|
||||
* Specifically, spaces should not appear at the beginning of a line, and tabs should not appear _except_ at the beginning of a line.
|
||||
* The sole exception is in a multiline `if` statement; the initial `if` should have four spaces before it to align it with an `elseif` on the next line. For example:
|
||||
|
||||
```lua
|
||||
---- 4 spaces
|
||||
if self.level < 900 then return 12
|
||||
elseif self.level < 1200 then return 8
|
||||
else return 6 end
|
||||
```
|
||||
|
||||
* Comments at the end of lines of code must be one line long. Multi-line comments must appear in their own block.
|
||||
|
||||
```lua
|
||||
if self.piece:isDropBlocked(self.grid) then
|
||||
-- this is a comment that appears in a block of its own, separate from any code
|
||||
-- consecutive multiline comments must have the same indentation level and
|
||||
-- not appear next on the same line as actual code
|
||||
self.drop_bonus = math.min(self.drop_bonus - 1, 0) -- comments at the end of a line must stay on that line
|
||||
else
|
||||
if piece_dy >= 1 then -- basically
|
||||
self.drop_bonus = self.drop_bonus + piece_dy * 20 -- this sort of
|
||||
end -- multiline comment
|
||||
self.drop_bonus = self.drop_bonus + 1 -- is completely
|
||||
end -- unacceptable
|
||||
```
|
||||
|
||||
* Use `snake_case` for variables, `camelCase` for functions.
|
||||
|
||||
```lua
|
||||
function MyGameMode:on_activate_bleep_bloop()
|
||||
-- no, bad, use "onActivateBleepBloop"
|
||||
local bleepBloopFrames = 240
|
||||
-- this is also bad, use "bleep_bloop_frames"
|
||||
local bleep_bloop_bonus = self.lock_delay * 150
|
||||
self.bleepBloopSubscore = self.bleepBloopSubscore + bleep_bloop_bonus
|
||||
-- member variables are also variables, this should be "bleep_bloop_subscore"
|
||||
end
|
||||
```
|
||||
|
||||
|
||||
Contributor's License Agreement
|
||||
-------------------------------
|
||||
|
||||
@ -50,3 +6,93 @@ By contributing source code or other assets (e.g. music, artwork, graphics) to C
|
||||
You also waive all moral rights to your contributions insofar as they are used in the Cambridge repository or in any code or works deriving therefrom.
|
||||
|
||||
(Notwithstanding the above clause, I will still make my best effort to provide sufficient attribution to all contributions. At the very least you'll get documentation of your contributions under SOURCES, and probably a special place in the credit roll as well.)
|
||||
|
||||
|
||||
Git / Repo conventions
|
||||
----------------------
|
||||
|
||||
In general, use `kebab-case` for branch names. Also, make sure they're concise and descriptive - like 2 or 3 words is usually good.
|
||||
|
||||
```
|
||||
* badbeef (badBranchName) This branch name is bad.
|
||||
| * defaced (another_bad_branch_name) This branch name is also bad because it uses snake case.
|
||||
|/
|
||||
| * deadcab (generic) This branch name isn't very descriptive.
|
||||
|/
|
||||
| * bac0040 (this-long-winded-branch-name-that-could-be-its-own-commit-message) Self-explanatory.
|
||||
|/
|
||||
| * 600db01 (good-branch-name) This branch name is good.
|
||||
|/
|
||||
* 0000420 (HEAD -> master, tag: v0.6.9) This is a sexy root commit.
|
||||
```
|
||||
|
||||
The top line of a commit message should generally be one full sentence long, without too many subordinate clauses. Don't sweat 50/72, but try not go over about 100 characters either.
|
||||
* If the message starts with a verb, it should be written in the past tense, as a description of what the commit _did_ to the commit tree. (e.g. _Made_ a change, _Fixed_ a bug, _Added_ a feature)
|
||||
* Alternatively, include a description (in the present tense) of what is now true thanks to this commit. (e.g. "The Puyo Puyo mode can now support up to 50 players.")
|
||||
|
||||
```
|
||||
* 800000d (message-too-long) Made multiplayer stuff play well with the new v0.2.5 server by fixing a problem the client was having with sending multiple 4-KB packets within 2 milliseconds of each other.
|
||||
| * defaced (not-descriptive-enough) Fixed stuff.
|
||||
|/
|
||||
| * bad0003 (present-tense) Lengthens the retry period of the server connection to 15 seconds.
|
||||
|/
|
||||
| * bad0004 (imperative-mood) Force the credit roll to end after 67 seconds if no input is detected.
|
||||
|/
|
||||
| * 600d001 (good-commit-summary) Made the Jenny Marathon mode not top out randomly at level 600.
|
||||
| * 600d002 (also-good) Backgrounds don't suck anymore.
|
||||
|/
|
||||
* 1234567 (HEAD -> master, tag: v0.4.2) Updated docs in preparation for a new release.
|
||||
```
|
||||
|
||||
When making pull requests, always include:
|
||||
|
||||
* A title that works well as a commit title, since that's what's going to appear when it's merged.
|
||||
* A full description of the problem that the pull request solves or the feature that it implements.
|
||||
* If the whole purpose of the pull request is to resolve a particular issue and nothing else, "Fixes #[issue number]" counts as a full description. Otherwise if there's anything else in the pull request, make a short note of "also [did this other thing]".
|
||||
|
||||
|
||||
Coding conventions
|
||||
------------------
|
||||
|
||||
Use tabs to indent, spaces to align.
|
||||
|
||||
* Specifically, spaces should not appear at the beginning of a line, and tabs should not appear _except_ at the beginning of a line.
|
||||
* The sole exception is in a multiline `if` statement; the initial `if` should have four spaces before it to align it with an `elseif` on the next line. For example:
|
||||
|
||||
```lua
|
||||
---- 4 spaces
|
||||
if self.level < 900 then return 12
|
||||
elseif self.level < 1200 then return 8
|
||||
else return 6 end
|
||||
```
|
||||
|
||||
Comments at the end of lines of code must be one line long. Multi-line comments must appear in their own block.
|
||||
|
||||
```lua
|
||||
if not self.piece:isDropBlocked(self.grid) then
|
||||
-- this is a comment that appears in a block of its own, separate from any code
|
||||
-- consecutive multiline comments must have the same indentation level and
|
||||
-- not appear next on the same line as actual code
|
||||
self.drop_bonus = 0 -- comments at the end of a line must stay on that line
|
||||
else
|
||||
if piece_dy >= 1 then -- basically
|
||||
self.drop_bonus = self.drop_bonus + piece_dy * 20 -- this sort of
|
||||
end -- multiline comment
|
||||
self.drop_bonus = self.drop_bonus + 1 -- is completely
|
||||
end -- unacceptable
|
||||
```
|
||||
|
||||
Use `snake_case` for variables, `camelCase` for functions.
|
||||
|
||||
```lua
|
||||
function MyGameMode:on_activate_bleep_bloop()
|
||||
-- no, bad, use "onActivateBleepBloop"
|
||||
|
||||
local bleepBloopFrames = 240
|
||||
-- this is also bad, use "bleep_bloop_frames"
|
||||
|
||||
local bleep_bloop_bonus = self.lock_delay * 150
|
||||
self.bleepBloopSubscore = self.bleepBloopSubscore + bleep_bloop_bonus
|
||||
-- this should be self."bleep_bloop_subscore", member variables are also variables
|
||||
end
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user