You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+59-14Lines changed: 59 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,34 +8,79 @@ Also, please consider adding your name and github in the vmaware.hpp file and th
8
8
9
9
10
10
## Translations
11
-
If you're making translations, please make sure that you actually speak the language, and you have the intention to be as accurate as possible.
12
-
13
-
What you SHOULDN'T translate are:
14
-
- text that's in a codeblock
15
-
- text in images
16
-
- text of usernames
17
-
- code
18
-
- and other stuff that should obviously not be translated.
11
+
If you're making translations, please make sure that you have the intention to be as accurate as possible. If you're unsure which parts should be translated or not, you can use the other translated files as a reference to guide you.
19
12
20
13
Using translation software like google translate is allowed, but only if you cross-check between the english and translation version to verify if it's done correctly.
21
14
22
15
The README is quite big, so this is quite an effort. I'm sure you have better thing to do in your life but if you can do this, it would be greatly appreciated :)
23
16
24
17
25
18
## Code contributions
26
-
If you're making code changes to the cli or header file, we have a useful script at `auxiliary/updater.py` that will update:
27
-
- the section line numbers in the header banner
28
-
- the date of the update
29
-
- and the library documentation for technique links
30
-
31
-
It's highly recommended to use this script before sending the PR so that all the above don't have to be manually updated, which can be time consuming and can potentially creep in some human errors.
19
+
The general rules are:
20
+
- Keep it C++11 compatible, this is extremely important
21
+
- Use snake_case
22
+
- Be as simple as possible
23
+
- Prefer readability over aggressive optimisations (especially intrinsics)
24
+
- Keep indentations at a minimum
25
+
- Don't create huge one-liners, try to break down statements line by line
26
+
- Write as few lines as possible for what you're trying to achieve
27
+
- Document your code and intentions very clearly, but don't overdo them for very obvious code.
28
+
- Avoid `std::function`, `std::shared_ptr`, `std::bind`, `std::list`, or very obscure C++ features.
29
+
- Indent size should be 4 spaces
30
+
31
+
There are other formatting rules, which will be covered with a demonstration:
32
+
33
+
```cpp
34
+
intmain() {
35
+
const u32 number = 10; // 1. use const whenever it should be used.
36
+
// 2. use the rust integral type convention from 8 to 64 (i.e. i8, u16, u64, etc...)
37
+
// 3. keep the names as simple and clear as possible, don't call it "n", call it "number".
38
+
// Try to name the variables into something that can universally be discerned by anybody,
39
+
// Make sure it's also context-aware and should make sense. Calling it "tmp" is also fine.
40
+
// Consistency is also key in this aspect, don't do "u32 number = find_num()", do find_number().
41
+
42
+
if (number >= 54) { // 4. avoid magic numbers, put a comment or make a constexpr variable prior to using it,
43
+
something(); // preferably the latter.
44
+
} else if (number) { // 5. make the if, else if, and else statement lines the same without breaking lines, so don't do:
45
+
something_else(); // if ()
46
+
} // {
47
+
// something();
48
+
// }
49
+
// else
50
+
// {
51
+
// something_else();
52
+
// }
53
+
//
54
+
// try to follow as shown in this actual demonstration.
55
+
56
+
if (
57
+
((number % 4) == 0) && // 6. use separate lines for each statement of a condition check. While this might look ok
58
+
(number > 50) && // on a single line, in practice your conditions will most likely not be as short and
59
+
(number < 100) // and simple as this. Try to avoid multiple condition checks in a single line for simplicity.
60
+
) {
61
+
something()
62
+
}
63
+
64
+
65
+
for (u8 i = 0; i < number; i++) { // 6. Be as simple as possible without using fancy features like iterators if it's not necessary.
66
+
something();
67
+
}
68
+
69
+
// Other rules will be added in the future, this is just a rough guideline for the moment.
70
+
}
71
+
```
72
+
73
+
> [!WARNING]
74
+
> ## Note from the developer:
75
+
> It should be mentioned that not all of the codebase is formatted this way. This standard guideline has been introduced 2 years after the project has started, and the lack of any guideline has resulted in the codebase looking fragmented, inconsistent, and very different in some portions due to differing coding styles among developers. This is completely my fault, and it has accumulated technical debt over the years. Although the current state isn't formatted consistently, the guideline is meant to slowly evolve the library into a much simpler version that's approachable to anybody trying to contribute and read through the code.
32
76
33
77
34
78
## I want to add a new technique, how would I do that?
35
79
There's a few steps that should be taken:
36
80
1. Make sure to add the technique name in the enums of all the techniques in the appropriate place.
37
81
2. Add the technique function itself in the technique section of the library. Make sure to add it in the right place, as there's preprocessor directives for each platform (Linux, Windows, and Apple)
38
82
3. Add the technique in the technique table situated at the end of the header file. The score should be between 10 and 100. Although there are exceptions, it's advised to follow the aforementioned score range.
0 commit comments