Skip to content

Commit af97443

Browse files
lucasstarszlucasstarsz
authored
Update contributing guidelines (#173)
- add unit test, spotless, code comments, logging info - Create contributing-examples.md - add contributing examples reference
1 parent 94d8fcf commit af97443

3 files changed

Lines changed: 159 additions & 37 deletions

File tree

‎.github/CONTRIBUTING.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ This project has been growing well on its own, but with the addition of new feat
1212
### Contributing Code
1313
For contributing code, please follow along with the guidelines outlined [here][Contributing-Code].
1414

15+
### Contributing Examples
16+
For contributing code examples, please follow along with the guidelines outlined [here][Contributing-Examples].
17+
1518
### Contributing Documentation
1619
For contributing api/website documentation, please follow along with the guidelines outlined [here][Contributing-Documentation].
1720

@@ -20,5 +23,6 @@ For guidelines on opening an issue, please follow along with the guidelines outl
2023

2124

2225
[Contributing-Code]: /.github/contributing/contributing-code.md "Contributing Code"
26+
[Contributing-Examples]: /.github/contributing/contributing-examples.md "Contributing Code Examples"
2327
[Contributing-Documentation]: /.github/contributing/contributing-documentation.md "Contributing Documentation"
2428
[Opening-An-Issue]: /.github/contributing/opening-issues.md "Opening Issues"

‎.github/contributing/contributing-code.md‎

Lines changed: 66 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -2,85 +2,114 @@
22

33
I've no clue how I managed to spend 3 years learning software development without using a proper IDE for developing larger projects. From the first days of FastJ I quickly realized I needed a rule set for how my code should be written.
44

5-
- [IDE](#IDE)
6-
- [Imports](#Imports)
7-
- [General Code Style](#General-Code-Style)
8-
- [Column Limit](#Column-Limit)
9-
- [Block Indentation](#Block-Indentation)
10-
- [Wildcard Imports](#Wildcard-Imports)
11-
- [Annotations](#Annotations)
12-
- [Constant Names](#Constant-Names)
13-
- [Type Variable Names](#Type-Variable-Names)
14-
- [Camel Case Defined](#Camel-Case-Defined)
15-
- [API Documentation](#API-Documentation)
16-
- [Be Clear](#Be-Clear)
17-
- [Be Thoroughly Concise](#Be-Thoroughly-Concise)
18-
- [Website Documentation](#Website-Documentation)
19-
205

216
## IDE
227
I absolutely prefer that you use [IntelliJ IDEA][IntelliJ-Link] while developing FastJ, but [Eclipse][Eclipse-Link] is fairly capable of keeping up as well. VSCode, _I'm personally not a fan of it_ -- it's given me a lot of trouble for Java development in the past, and I don't plan on using it for bigger Java projects any time soon. However, as long as you can get the job done in whatever you're comfortable with you're free to use it.
238

249

25-
## Imports
26-
There's a specific order your imports should follow:
27-
```java
28-
import io.github.lucasstarsz.fastj.engine.*;
29-
import io.github.lucasstarsz.fastj.math.*;
30-
import io.github.lucasstarsz.fastj.graphics.*;
31-
32-
import io.github.lucasstarsz.fastj.systems.*;
33-
34-
import java.*;
35-
import javax.*;
10+
## Spotless
11+
[diffplug/spotless](https://github.com/diffplug/spotless) handles all import styling, and a little bit of general code formatting as well.
3612

37-
import others
38-
39-
import static others
40-
41-
public class ... {
42-
}
43-
```
44-
45-
A bit excessive, but for me (the owner of the repo, lucasstarsz, hi) it provides the most optimal reading -- not that anyone else reads them.
13+
**Remember to run `gradlew spotlessApply` on your code**. On pull requests, the GitHub Action scripts will all check whether the code is formatted according to `spotless`' liking. If it is not formatted, the checks will fail. Please keep this in mind!
4614

4715

4816
## General Code Style
4917
For the most part, you can follow along with this codebase using [Google's Java Style Guide][Style-Guide-Link]. It covers most of the bases, with exceptions as follows:
5018

19+
5120
### Column Limit
5221
Other than JUnit test asserts, Markdown, and Git commits -- I don't care about the exact style of these in terms of this, Lines should hard-wrap at the **120-character** limit, and not at 100.
5322

23+
5424
### Block Indentation
5525
Indentation must be **4 spaces**. Indentations for method chaining must be **8 spaces**.
56-
26+
27+
5728
### Wildcard Imports
5829
Wildcard imports are only allowed if the file's import count from that specific package is more than 10, with the same situation being applied to static imports more than 7.
5930

31+
6032
### Annotations
6133
For the sake of my own sanity, until further notice I will not allow the exception regarding single parameterless annotations for methods. However:
6234
- Single parameterless annotations for a field are always welcome to be on the same line.
6335
- Otherwise, annotations must always be on a line of its own (one annotation per line).
6436

37+
6538
### Constant Names
6639
All constant values (`static final`, `enum`) should follow `PascalCase`, rather than `CONSTANT_CASE`.
6740
- Furthermore, shallow constants (e.g. `static final Set<Integer>`) should _also_ use `PascalCase`.
6841

42+
6943
### Type Variable Names
7044
I have no preference on how these are named.
7145

46+
7247
### Acronyms in Variable Names
7348
So long as they are only used when it makes the most sense to (e.g. FPS, UPS, or GL in the context of OpenGL), they are preferred. If it is not something easily recognized by acronym, it should not be given one (e.g. FJGL -- FastJ Game Library).
7449

7550

51+
## Code Comments
52+
If the code calls for it, please do provide some. It may also be a sign that your code could otherwise be simplified 😛
53+
- Comments, wither single or multi-block, should remain within 100 characters long. The rest should be on a new line.
54+
- If a comment is found to be unhelpful or otherwise redundant in a PR, the PR may not be allowed to merge until the usage of those comments is discussed thoroughly.
55+
56+
7657
## Documentation
7758
Please see [Contributing Documentation][Contributing-Documentation].
7859

60+
61+
## Logging
62+
FastJ uses [SimpleLogger]() as its supplementary logging library to `SLF4J`. As such, the `test` section contains a `simpleLogger.properties` file that can be edited -- but preferably not updated -- over time.
63+
- Use `Log.`, and not `FastJEngine.` in your logging -- each logging statement should specify which class it comes from.
64+
- Use message parameterization -- review [this section of SLF4J's documentation](https://www.slf4j.org/faq.html#logging_performance) for more details.
65+
66+
An example of the expected logging scheme is provided below:
67+
```java
68+
Log.warn(MyClass, "message {}", formattedContent);
69+
```
70+
71+
7972
## Unit Tests
80-
Unit Tests are an integral part of the project. No part of the project should be left untested -- I am currently working hard to give this project as much unit testing as possible.
73+
Unit Tests are an essential part of the project's success. No part of the project should be left untested -- I am currently working hard to give this project as much unit testing as possible.
8174

8275
New code added to the repository should **always** be accompanied by unit testing. There is no exception to this -- PRs without unit tests for new methods added (of course, there are exceptions to this rule) will **not** be merged.
8376

77+
FastJ makes use of [JUnit 5](https://junit.org/junit5/) for its unit testing purposes. If you're not directly familiar with this version of JUnit (as it has some key differences from its predecessor JUnit 4) please make sure you read through the JUnit guide before/while you write your unit tests.
78+
- [Webpage/Docs version of the guide](https://junit.org/junit5/docs/current/user-guide/)
79+
- [PDF version of the guide](https://junit.org/junit5/docs/current/user-guide/junit-user-guide-5.8.2.pdf)
80+
81+
### Visibility
82+
- All unit test classes and test cases should have `package-private` visiblity.
83+
- All other components to the unit tests should be given visibility based on best judgement.
84+
- All packages in `unittest` that contain classes with test cases should be opened to `junit-platform-commons` in the `module-info.java` file, for example:
85+
```java
86+
// inside module-info.java
87+
opens unittest.testcases.graphics to org.junit.platform.commons;
88+
```
89+
90+
91+
### Naming
92+
- Classes should contain test cases regarding the topic being tested against.
93+
- For checking normal assertions:
94+
```java
95+
@Test
96+
void checkSomeThingAction<_withOtherRelatedInformation><_shouldPerformAction>() {}
97+
98+
@Test
99+
void checkSomeThings_SpecificInformation() {}
100+
```
101+
- For exception-related assertions:
102+
```java
103+
@Test
104+
void tryErroneousAction<_withInvalidOrErroneousParameters>_shouldThrowExceptionOrSomeOtherAction() {}
105+
```
106+
- For `BeforeAll` assumptions:
107+
```java
108+
@BeforeAll
109+
public static void onlyRunIfSomeCondition() {}
110+
```
111+
Items in `<>` are optional.
112+
84113

85114
[IntelliJ-Link]: https://www.jetbrains.com/idea/ "IntelliJ IDEA IDE"
86115
[Eclipse-Link]: https://www.eclipse.org/downloads/ "Eclipse IDE"

‎.github/contributing/contributing-examples.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Contributing Examples
2+
3+
## Picking an Example Topic
4+
Head to [FastJ issue #20](https://github.com/fastjengine/FastJ/issues/20) to find examples that need creating!
5+
6+
7+
## Setting Up the Example
8+
- Inside of the `examples` subproject, create a package inside `tech.fastj.examples` regarding your example program.
9+
- Inside of your new package, create a class called `Main.java`. **It is extremely important that your example's main class is named Main.java.** Without this, you will not be able to run the example through the examples:run task.
10+
11+
## Writing the Example
12+
- Follow FastJ's [code contribution convention guide](https://github.com/fastjengine/FastJ/blob/main/.github/contributing/contributing-code.md) while writing your example -- deviations from this style guide will result in PR checks failing.
13+
- Explain the process! Your audience is likely students and other programmers with minimal java experience, if any. Your program should be covering:
14+
- How the feature being covered works as a whole
15+
- What it provides in terms of usefulness
16+
- The different components of the feature, and how to use each one (with both code and comments)
17+
- Don't have the user normally run code that will crash with an exception. Not only does this mean to cheeck your code, but also to leave explanatory code that would cause an exception, _commented_. Let the reader uncomment the code for themselves if they would like to test and see what happens in real time.
18+
- Explain code you wrote if it's not directly used:
19+
```java
20+
/* For the sake of this example, ... */
21+
```
22+
- Leave methods that don't pertain to the engine usefulness with a single comment:
23+
```java
24+
// Empty -- this example does not make use of this method.
25+
```
26+
27+
A decent example of all of these concepts combined: (from `tech.fastj.example.audio`)
28+
```java
29+
package tech.fastj.examples.audio;
30+
31+
import tech.fastj.engine.FastJEngine;
32+
33+
import tech.fastj.systems.audio.AudioManager;
34+
35+
import java.nio.file.Path;
36+
import java.util.concurrent.TimeUnit;
37+
38+
public class Main {
39+
public static void main(String[] args) throws InterruptedException {
40+
/* Simple FastJ Audio */
41+
42+
/* FastJ's audio engine provides a simple way to play audio: AudioManager.playSound.
43+
* This is the method you'll want to use to play audio without any hassle -- it can be
44+
* called from anywhere, and will work to be as efficient as possible while playing.
45+
*
46+
* The method takes in a filepath -- the filepath to your sound file. A filepath can be
47+
* either a Path or a URL. */
48+
49+
/* - A Path (java.nio.file.Path) is as what it implies -- a path to a file.
50+
*
51+
* This works best for situations where you don't need code portability -- with the
52+
* existence of Path.of("path/to/some/audio.wav"), you'll have little-to-no trouble
53+
* determining where the path leads.
54+
*
55+
* However, this comes at the cost of having a much harder time using the code in a
56+
* distributed format. Path resolves its paths based on where the program is called,
57+
* which most of the time does not work for programs that have shortcuts (like most
58+
* executables on Windows!) */
59+
FastJEngine.log("Now playing: test_audio.wav from file Path");
60+
AudioManager.playSound(Path.of("resources/sound/test_audio.wav"));
61+
62+
63+
/* For the sake of this example, I've put a second of sleep time after each audio sound.
64+
* This gives you a chance to hear the audio being played. */
65+
TimeUnit.SECONDS.sleep(1);
66+
67+
68+
/* Now, let's look at the second option: a URL.
69+
* - A URL (java.net.URL) is also a path to a file, but with slightly different rules and
70+
* configuration.
71+
*
72+
* A URL takes a bit more to set up in our case -- it requires a class loader, which you
73+
* can get using:
74+
*
75+
* YourClass.class.getClassLoader();
76+
*
77+
* The cool thing about class loaders, however, is that they manage resources much easier
78+
* than Path does when it comes to portable files. The usage below will work inside a
79+
* jarfile as well as outside one. */
80+
FastJEngine.log("Now playing: test_audio.wav from URL");
81+
AudioManager.playSound(Main.class.getClassLoader().getResource("sound/test_audio.wav"));
82+
83+
84+
/* For the sake of this example, I've put a second of sleep time after each audio sound.
85+
* This gives you a chance to hear the audio being played. */
86+
TimeUnit.SECONDS.sleep(1);
87+
}
88+
}
89+
```

0 commit comments

Comments
 (0)