-
Notifications
You must be signed in to change notification settings - Fork 122
Contribution guidelines
Michel Jung edited this page May 20, 2016
·
41 revisions
Read http://blog.codinghorror.com/the-ten-commandments-of-egoless-programming/
Developers spend about 25% writing code, but 75% reading it. Writing readable code saves a lot of time.
- Keep the coding style consistent
- Prefer longer, unambiguous names over short but ambiguous ones
- Prefer slower but easily readable code over short/fast but hard to read code (if it doesn't noticeable affect performance)
- Even small things matter; If a character (e.g. whitespace) is superfluous, remove it, if it is missing, add it.
Yes, I said avoid them. Despite what is commonly thought, comments are practice. See examples here.
While quick and dirty implementations may save time in the short run, they will cost more in the long run.
- "Quick and dirty" is almost never an option, there is only "clean and solid"
- Always mark temporary or unfinished solutions using either
TODO
orFIXME
with an explaining comment- Use
FIXME
for code that is wrong or missing - Use
TODO
for code that works, but needs to be improved
- Use
- Make sure there is an issue on Github and assign it to yourself
- Create a new branch for the feature, based on latest
master
. Name itfeature/#00-some-keywords
where00
is the issue ID andsome-keywords
are keywords that �outline the issue. Example:feature/#23-auto-update
- Always include the issue ID in a commit comment, e. g.
#23 implemented update task
To be considered as "done", a feature must:
- Have >80% test coverage (line & branch)
- Be reviewed by another contributor
- Be ready to be merged into
master
- Always use SLF4J logger (copy from existing classes)
- Never use
System.out
- Put interesting information in front, additional information at the end
- Put values either in single quotes or after colons. Example:
User '{}' sent message: {}
Log level | When to use | When not to use | Example |
---|---|---|---|
TRACE |
Information that is low level and only of interest during development. | Any other purpose | Network traffic, Received 512 bytes from FA , Creating directory xxx
|
DEBUG |
Information that is important to understand problems. Use for repeating things. | Any other purpose | Received game info from server: GameInfo{uid=3876249, title='All welcome!!!', state=OPEN} |
INFO |
Events that are interesting ("milestones"). | For repeating things | Connected to server at lobby.faforever.com:8167 |
WARN |
Events that need attention but don't lead to malfunction | Any other purpose | Could not connect to lobby.faforever.com:8167 |
ERROR |
If, and only if, something is unexpected, unrecoverable or leads to data loss or malfunction | Things that are recoverable | Cannot read client.prefs |