Proofread

Author: jserv

CONTRIBUTING.md

@@ -2,42 +2,57 @@
 
 :+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
 
-The following is a set of guidelines for contributing to [semu](https://github.com/jserv/semu)
-hosted on GitHub. These are mostly guidelines, not rules. Use your best
-judgment, and feel free to propose changes to this document in a pull request.
+The following is a set of guidelines for contributing to [semu](https://github.com/sysprog21/semu)
+hosted on GitHub. These are mostly guidelines, not rules.
+Use your best judgment, and feel free to propose changes to this document in a pull request.
 
 ## Issues
 
-This project uses GitHub Issues to track ongoing development, discuss project plans, and keep track of bugs. Be sure to search for existing issues before you create another one.
+This project uses GitHub Issues to track ongoing development, discuss project plans, and keep track of bugs.
+Be sure to search for existing issues before you create another one.
 
-Visit our [Issues page on GitHub](https://github.com/jserv/semu/issues) to search and submit.
+Visit our [Issues page on GitHub](https://github.com/sysprog21/semu/issues) to search and submit.
 
 ## Coding Convention
 
-We welcome all contributions from corporate, academic and individual developers. However, there are a number of fundamental ground rules that you must adhere to in order to participate. These rules are outlined as follows:
-* All code must adhere to the existing C coding style (see below). While we are somewhat flexible in basic style, you will adhere to what is currently in place. Uncommented, complicated algorithmic constructs will be rejected.
-* All external pull requests must contain sufficient documentation in the pull request comments in order to be accepted.
+Contributions from developers across corporations, academia, and individuals are welcome.
+However, participation requires adherence to fundamental ground rules:
+* Code must strictly adhere to the established C coding style (refer to the guidelines below).
+  While there is some flexibility in basic style, it is crucial to stick to the current coding standards.
+  Complex algorithmic constructs without proper comments will not be accepted.
+* External pull requests should include thorough documentation in the pull request comments for consideration.
 
 Software requirement: [clang-format](https://clang.llvm.org/docs/ClangFormat.html) version 12 or later.
 
-Use the command `$ clang-format -i *.[ch]` to enforce a consistent coding style.
+This repository consistently contains an up-to-date `.clang-format` file with rules that match the explained ones.
+For maintaining a uniform coding style, execute the command `clang-format -i *.[ch]`.
 
 ## Coding Style for Modern C
 
-This coding style is a variation of the K&R style. Some general principles: honor tradition, but accept progress; be consistent;
-embrace the latest C standards; embrace modern compilers, their static analysis
-capabilities and sanitizers.
+This coding style is a variant of the K&R style.
+Adhere to established practices while being open to innovation.
+Maintain consistency, adopt the latest C standards,
+and embrace modern compilers along with their advanced static analysis capabilities and sanitizers.
 
 ### Indentation
 
-Use 4 spaces rather than tabs.
+In this coding style guide, the use of 4 spaces for indentation instead of tabs is strongly enforced to ensure consistency.
+Consistently apply a single space before and after comparison and assignment operators to maintain readable code.
+Additionally, it is crucial to include a single space after every comma.
+e.g.,
+```c
+for (int i = 0; i < 10; i++) {
+    printf("%d\n", i);
+    /* some operations */
+}
+```
 
 ### Line length
 
-All lines should generally be within 80 characters.  Wrap long lines.
-There are some good reasons behind this:
-* It forces the developer to write more succinct code;
-* Humans are better at processing information in smaller quantity portions;
+All lines should typically stay within 80 characters, and longer lines should be wrapped.
+There are valid rationales for this practice:
+* It encourages concise code writing by developers.
+* Smaller portions of information are easier for humans to process.
 * It helps users of vi/vim (and potentially other editors) who use vertical splits.
 
 ### Comments
@@ -66,7 +81,12 @@ Leave two spaces between the statement and the inline comment.
 ### Spacing and brackets
 
 Use one space after the conditional or loop keyword, no spaces around
-their brackets, and one space before the opening curly bracket.
+their brackets, and one space before the opening curly bracket. e.g.,
+```c
+do {
+    /* some operations */
+} while (condition);
+```
 
 Functions (their declarations or calls), `sizeof` operator or similar
 macros shall not have a space after their name/keyword or around the
@@ -81,6 +101,8 @@ but otherwise avoid redundant or excessive brackets.
 
 ### Variable names and declarations
 
+- Ensure that functions, variables, and comments are consistently named using English names/text.
+
 - Use descriptive names for global variables and short names for locals.
 Find the right balance between descriptive and succinct.
 
@@ -97,6 +119,29 @@ const uint8_t * const charmap;  /* const pointer and const data */
 const void * restrict key;  /* const pointer which does not alias */
 ```
 
+- Local variables of the same type should be declared in the same line.
+```c
+void func(void)
+{
+    char a, b; /* OK */
+
+    char a;
+    char b;    /* Incorrect: A variable with char type already exists. */
+}
+```
+
+- Always include a trailing comma in the last element of structure initialization, including its children, to assist clang-format in correctly formatting structures. However, this can be omitted in very simple and short structures.
+```c
+typedef struct {
+    int width, height;
+} screen_t;
+
+screen_t s = {
+    .width = 640,
+    .height = 480,   /* comma here */
+}
+```
+
 ### Type definitions
 
 Declarations shall be on the same line, e.g.,
@@ -418,9 +463,9 @@ printf("val %lld\n", SOME_CONSTANT);
 
 #### Avoid unaligned access
 
-Do not assume unaligned access is safe.  It is not safe on Arm, POWER,
-and various other architectures.  Moreover, even on x86 unaligned access
-is slower.
+Avoid assuming that unaligned access is safe.
+It is not secure on architectures like Arm, POWER, and others.
+Additionally, even on x86, unaligned access can be slower.
 
 #### Avoid extreme portability