[gnome-games] HACKING: Merge with CodingStyle.txt
- From: Alexander Mikhaylenko <alexm src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-games] HACKING: Merge with CodingStyle.txt
- Date: Thu, 14 May 2020 16:59:16 +0000 (UTC)
commit d5dc3a6e01e798ecf139ceee0ee3780ef251de05
Author: j-warmbier <joris warmbier net>
Date: Thu May 14 13:49:00 2020 +0200
HACKING: Merge with CodingStyle.txt
HACKING references CodingStyle.txt, both have different structure.
Having two files can confuse developers.
Merge the information, make extra headings for the Vala Code and C Code
parts of the Coding Style Guidelines. Update UI Guidelines to not
include two separate headerbars.
https://gitlab.gnome.org/GNOME/gnome-games/-/issues/281
CodingStyle.txt | 231 ------------------------------------------------
HACKING | 92 -------------------
HACKING.md | 268 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.md | 2 +-
4 files changed, 269 insertions(+), 324 deletions(-)
---
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 00000000..1c188056
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,268 @@
+# Compilation and Installation Procedure
+You can install this project either manually (by command line) or with
[Builder](https://wiki.gnome.org/Apps/Builder "GNOME-Builder Wiki").
+
+## Manual installation
+### Get the official git repository
+```shell
+git clone https://gitlab.gnome.org/GNOME/gnome-games.git
+```
+
+### Get dependencies
+Games always requires the matching version of [retro-gtk](https://gitlab.gnome.org/GNOME/retro-gtk
"Retro-GTK GitLab"), [libmanette](https:/gitlab.gnome.org/aplazas/libmanette "libmanette GitLab") and
[libhandy](https://source.puri.sm/Librem5/libhandy "libhandy"), so if you use the master version of Games,
you need to use the master version of retro-gtk, libmanette and libhandy.
+
+### Prepare compilation
+```shell
+meson _build
+```
+
+### Compilation
+``` shell
+ninja -C _build
+```
+
+### Install the application
+```shell
+sudo ninja -C _build install
+```
+
+# Coding Style Guidelines
+
+## Vala code
+The coding style to respect in this project is very similar to most Vala projects.
+
+* Use 4-spaces wide tabs (and not spaces) for indentation.
+
+* Use spaces for alignment.
+
+* _Prefer_ lines of less than <= 80 columns.
+
+* 1-space between function name and braces (both calls and signature declarations).
+
+* If a function signature/call fits in a single line, do not break it into multiple lines.
+
+* for methods/functions that take variable argument tuples, all the first elements of tuples are indented
normally with subsequent elements of each tuple indented 4-spaces more. Like this:
+```
+action.get ("ObjectID",
+ typeof (string),
+ out this.object.id,
+ "Filter",
+ typeof (string),
+ out this.filter,
+ "StartingIndex",
+ typeof (uint),
+ out this.index,
+ "RequestedCount",
+ typeof (uint),
+ out this.requested_count,
+ "Sortcriteria",
+ typeof (uint),
+ out this.sort_criteria);
+```
+
+* Single statements inside `if`/`else` must not be enclosed by `{}`.
+
+* Provide docs in comments, but avoid over-documenting while doing so. An example of a useless comment would
be:
+```
+//fetch the document
+fetch_the_document ();
+```
+
+* Add a newline to break the code into logical pieces.
+
+* Add a newline before each return, throw, break, continue etc. if it is not the only statement in that
block.
+```
+ if (condition_applies ()) {
+ do_something ();
+
+ return false;
+ }
+
+ if (other_condition_applies ())
+ return true;
+```
+
+ Except for the break in a switch:
+```
+ switch (val) {
+ case 1:
+ debug ("case 1");
+ do_one ();
+ break;
+
+ default:
+ ...
+ }
+```
+
+* Give the `case` statements the same indentation level as their `switch` statement.
+
+* Add a newline at the end of each file.
+
+* _Prefer_ descriptive names over abbreviations (unless well-known) & shortening of names. E.g. `discoverer`
over `disco`.
+
+* Use `var` in variable declarations wherever possible.
+
+* Don't use `var` when declaring a number from a literal.
+
+* Use `as` to cast wherever possible.
+
+* Avoid the use of the `this` keyword when possible.
+
+* Don't use any `using` statements.
+
+* Prefer `foreach` over `for`.
+
+* Each class should go in a separate .vala file which should be named according to the class in it, but in
kebab-case. E.g. the Games.GameSource class should go under game-source.vala.
+
+* Declare the namespace(s) of the class/errordomain with the class/errordomain itself. Like this:
+```
+private class Games.Hello {
+ ...
+};
+```
+
+* Use GObject-style construction whenever possible.
+
+* Prefer properties over methods whenever possible.
+
+* Declare properties getters before the setters.
+
+* If a function returns several equally important values, they should all be given out as arguments. In
other words, prefer this:
+```
+void get_a_and_b (out string a, out string b)
+```
+
+over this:
+```
+string get_a_and_b (out string b)
+```
+
+* Use method as callbacks to signals.
+
+* _Prefer_ operators over methods when possible. E.g. prefer `collection[key]` over `collection.get(key)`.
+
+* If a function or a method can be used as a callback, don't enclose it in a lambda. E.g. do `do (callback)`
rather than `do (() => callback ()) `.
+
+* Limit the try blocks to the code throwing the error.
+
+* Anything that can be `private` must be `private`.
+
+* Avoid usage of the `protected` visiblity
+
+* Use the `internal` visibility carefully.
+
+* Always add a comma after the enumerated value of an enum type.
+
+* Always add a comma after the final error code of an errordomain type.
+
+* Any `else`, `else if`, `catch` or any other special block
+ following another one should start in its own line and not on the
+ same as the previous closing brace.
+
+ * Internationalize error messages, which implies using printf style
+ string construction rather than string templates.
+
+ * Append the original error message to the one you are building when refining an error.
+
+## C code
+
+For C code, the following rules apply, inspired by several other GObject projects.
+
+* Use 2 spaces for indentation.
+
+* _Prefer_ lines of less than <= 80 columns
+
+* Leave a 1-space between function name and braces (both calls and signature)
+
+* Add a newline to break the code in logical pieces.
+
+* Add a newline before each `return`, `break`, `continue` etc. if it is not the only statement in that block.
+```
+if (condition_applies (self)) {
+ do_something (self);
+
+ return FALSE;
+ }
+
+ if (other_condition_applies ())
+ return TRUE;
+```
+
+* Give the `case` statements the same indentation level as their
+ `switch` statement.
+
+* Add a newline at the end of each file.
+
+* In C files, function definitions are split into lines in the following way:
+ + modifiers and the returned type at the beginning of the line;
+ + the function name and the first parameter (if any) at the beginning of the line;
+ + each extra parameter has its own line, aligned with the first
+parameter;
+ + the opening curly brace at the beginning of the line.
+
+* In header files, function definitions are split into lines in the following way:
+ + modifiers, the returned type, the function name and the first parameter (if any) at the beginning
of the line;
+ + each extra parameter has its own line, aligned with the first parameter;
+ + the opening curly brace at the beginning of the line.
+
+* Provide docs in comments, but avoid over-documenting while doing so. An example of a useless comment would
be:
+```
+//fetch the document
+fetch_the_document ();
+```
+
+* Any `else` , `else if` block or any other special block following another one should start in its own line
and not on the same as the previous closing brace.
+
+* _Prefer_ descriptive names over abbreviations (unless well-known) & shortening of names. E.g. `discoverer`
over `disco`.
+
+* Functions with no parameters should state it with the `void` keyword.
+
+* Use static functions instead of nested ones.
+
+* Don't use single statement blocks.
+
+* Each class should go in a separate .c and .h file which should be named according to the class in it, but
in kebab-case. E.g. the Games.GameSource class should go under game-source.h and game-source.c.
+
+* If a function returns several equally important values, they should all be given as out arguments. In
other words, prefer this:
+```
+void get_a_and_b (gchar **a, gchar **b)
+```
+
+over this:
+```
+gchar *get_a_and_b (gchar **b)
+```
+
+* Anything that can be `private` (`static` to the C file) must be
+ `private`.
+
+* Always add a comma after the enumerated value of an enum type broken into multiple lines.
+
+* Always add a comma after values of an array literal broken into
+ multiple lines.
+
+* Append the original error message to the one you are building when refining an error.
+
+# Commit Message Guidelines
+
+Follow GNOME's commit message guidelines: <https://wiki.gnome.org/Git/CommitMessages>
+To these rules we add some others.
+
+General rules:
+* In the description, try to fill your lines as much as possible (don't go to the next line when the word
you want to write still fits onto the current line).
+* Don't go to the next line after finishing a sentence if you still have enough space for more words.
+* Split the paragraphs with two newlines (one empty line).
+* If the context isn't sufficient, be explicit with the types and namespaces of the codepoints you cite.
+* Suffix methods and functions with parentheses (without the space) so other people know the name refers to
an operation when they read your commit.
+* Write property names between single quotes and in kebab-case.
+
+The tag can be:
+* The name of the sub-directory of data, plugins or src in which the change was made
+* `build` if it affects the build system
+* anything else that seems more appropriate for the change
+* nothing if multiple parts were affected
+
+The actual changes:
+* The first paragraph explains what the commit does from an objective point of view: the code change.
+* If the shortlog is explicit enough, this first paragraph can be omitted.
+* Try to start sentences by the action performed and try using the infinitive.
diff --git a/README.md b/README.md
index ad558d0f..a93bed38 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ speedrunning tools or video game development tools.
- IRC channel: #gnome-games on irc.gnome.org
## Contribution guide
-https://gitlab.gnome.org/GNOME/gnome-games/blob/master/HACKING
+https://gitlab.gnome.org/GNOME/gnome-games/blob/master/HACKING.md
## Developing
We support development using Flatpak via GNOME Builder. At the Builder
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]