New changes in the guide from Victor

info/guide/guide-chapter-0.md

@@ -20,16 +20,16 @@ For the code to be considered high-quality, it must entail the following charact
 Like other modern programming languages, Kotlin is an advanced programming language that complies with the following general principles:
 1.	Clarity — a necessary feature of programs that are easy to maintain and refactor.
 2.	Simplicity — a code is easy to understand and implement.
-3.	Consistency — enables a code to be easily modified, reviewed and understood by the team members. Unification is particularly important when the same team works on the same project, utilizing similar styles.enables code to be easily modified, reviewed and understood by the team members.
+3.	Consistency — enables a code to be easily modified, reviewed, and understood by the team members. Unification is particularly important when the same team works on the same project, utilizing similar styles enabling a code to be easily modified, reviewed, and understood by the team members.
 
 Also, we need to consider the following factors when programming on Kotlin:
 
 1. Writing clean and simple Kotlin code
 
     Kotlin combines two of the main programming paradigms: functional and object-oriented.
     Both of these paradigms are trusted and well-known software engineering practices.
-    As a young programming language, Kotlin is built on the top of well-established languages such as Java, C++, C#, and Scala.
-    This enables Kotlin to introduce many features that help you write cleaner, more readable code, while also reducing the number of complex code structures. For example, type and null safety, extension functions, infix syntax, immutability, val/var differentiation, expression-oriented features, when statements, much easier work with collections, type auto conversion, and other syntactic sugar.
+    As a young programming language, Kotlin is built on top of well-established languages such as Java, C++, C#, and Scala.
+    This enables Kotlin to introduce many features that help a developer write cleaner, more readable code while also reducing the number of complex code structures. For example, type and null safety, extension functions, infix syntax, immutability, val/var differentiation, expression-oriented features, "when" statements, much easier work with collections, type auto conversion, and other syntactic sugar.
 
 2. Following Kotlin idioms
 
@@ -59,6 +59,6 @@ Unless otherwise stated, this specification applies to versions 1.3 and later of
 ### <a name="c0.4"></a> Exceptions
 
 Even though exceptions may exist, it is essential to understand why rules and recommendations are needed.
-Depending on your project situation or personal habits, you can break some of the rules. However, remember that one exception may lead to many and eventually can destroy code consistency. As such, there should be very few exceptions.
+Depending on a project situation or personal habits, you can break some of the rules. However, remember that one exception may lead to many and eventually can destroy code consistency. As such, there should be very few exceptions.
 When modifying open-source code or third-party code, you can choose to use the code style from this open-source project (instead of using the existing specifications) to maintain consistency.
 Software that is directly based on the Android native operating system interface, such as the Android Framework, remains consistent with the Android style.

info/guide/guide-chapter-1.md

@@ -1,18 +1,18 @@
 # <a name="c1"></a> 1. Naming
-In programming, it is not always easy to meaningfully and appropriately name variables, functions, classes, etc. Using meaningful names helps you clearly express your code's main ideas and functionality and avoid misinterpretation, unnecessary coding and decoding, "magic" numbers, and inappropriate abbreviations.
+In programming, it is not always easy to meaningfully and appropriately name variables, functions, classes, etc. Using meaningful names helps to clearly express your code's main ideas and functionality and avoid misinterpretation, unnecessary coding and decoding, "magic" numbers, and inappropriate abbreviations.
 
 Note: The source file encoding format (including comments) must be UTF-8 only. The ASCII horizontal space character (0x20, that is, space) is the only permitted whitespace character. Tabs should not be used for indentation.
 
 <!-- =============================================================================== -->
 ### <a name="c1.1"></a> 1.1 Identifier names
-### <a name="r1.1.1"></a> 1.1.1: Identifiers naming conventions
+### <a name="r1.1.1"></a> Rule 1.1.1: Identifiers naming conventions
 
 For identifiers, use the following naming conventions:
 1.	All identifiers should use only ASCII letters or digits, and the names should match regular expressions `\w{2,64}`.
 Explanation: Each valid identifier name should match the regular expression `\w{2,64}`.
 `{2,64}` means that the name length is 2 to 64 characters, and the length of the variable name should be proportional to its life range, functionality, and responsibility.
 Name lengths of less than 31 characters are generally recommended. However, this depends on the project. Otherwise, a class declaration with generics or inheritance from a superclass can cause line breaking.
-No special prefix or suffix should be used in the names. The following examples are inappropriate: name_, mName, s_name, and kName.
+No special prefix or suffix should be used in names. The following examples are inappropriate names: name_, mName, s_name, and kName.
 
 2.	Choose file names that would describe the content. Use camel case (PascalCase) and `.kt` extension.
 
@@ -50,7 +50,7 @@ The only exception is function names in `Unit tests.`
 | n,h           | h,n                      | nr, head, height |
 | rn, m         | m,rn                     | mbr, item        |
 
-**Exceptions**
+**Exceptions:**
 - The i,j,k variables used in loops are part of the industry standard. One symbol can be used for such variables.
 - The `e` variable can be used to catch exceptions in catch block: `catch (e: Exception) {}`
 - The Java community generally does not recommend the use of prefixes. However, when developing Android code, you can use the s and m prefixes for static and non-public non-static fields, respectively.
@@ -69,12 +69,12 @@ Note that prefixing can also negatively affect the style and the auto-generation
 ### <a name="r1.2.1"></a> Rule 1.2.1: Package names dots
 Package names are in lower case and separated by dots. Code developed within your company should start with `your.company.domain.` Numbers are permitted in package names.
 Each file should have a `package` directive.
-Package names are all written in lowercase, and consecutive words are concatenated together (no underscores). Package names should contain both the product and module names, and the department (or team) name to prevent conflicts with other teams.  Numbers are not permitted. For example: `org.apache.commons.lang3`, `xxx.yyy.v2`.
+Package names are all written in lowercase, and consecutive words are concatenated together (no underscores). Package names should contain both the product or module names and the department (or team) name to prevent conflicts with other teams.  Numbers are not permitted. For example: `org.apache.commons.lang3`, `xxx.yyy.v2`.
 
 **Exceptions:** 
 
 - In certain cases, such as open-source projects or commercial cooperation, package names should not start with `your.company.domain.`
-- If the package name starts with a number or other characters that cannot be used at the beginning of the Java/Kotlin package name, then underscores are allowed. For example: `com.example._123name`.
+- If the package name starts with a number or other character that cannot be used at the beginning of the Java/Kotlin package name, then underscores are allowed. For example: `com.example._123name`.
 - Underscores are sometimes permitted if the package name contains reserved Java/Kotlin keywords, such as `org.example.hyphenated_name`, `int_.example`.
 
 **Valid example**: 
@@ -114,7 +114,7 @@ class Order {}
 Function names should use `lowerCamelCase` nomenclature. Follow the naming rules described below:
 1.	Function names are usually verbs or verb phrases denoted with the camel case nomenclature (`lowerCamelCase`).
 For example: `sendMessage`, `stopProcess`, or `calculateValue`.
-To name functions use the following formatting rules:
+To name functions, use the following formatting rules:
 
 a) To get, modify, or calculate a certain value: get + non-boolean field(). Note that the Kotlin compiler automatically generates getters for some classes, applying the special syntax preferred for the 'get' fields: kotlin private val field: String get() { }. kotlin private val field: String get() { }.
 ```kotlin
@@ -164,17 +164,17 @@ fun addKeyListener(Listener)
 Constant names should be in UPPER case, words separated by underscore. The jeneral constant naming conventions are listed below:
 1. Constants are attributes created with the `const` keyword, or top-level/`val` local variables of an object that holds immutable data. In most cases, constants can be identified as a `const val` property from the `object`/`companion object`/file top level. These variables contain a fixed constant values that typically should never be changed by programmers. This includes basic types, strings, immutable types, and immutable collections of immutable types. The value is not constant for the object, which state can be changed.
 
-1. Constants are attributes created with the const keyword, or top-level/`val` local variables of an object that holds immutable data. In most cases, constants can be identified as a `const val` property from the `object`/`companion object`/file top level. These variables contain a fixed constant value that typically should never be changed by programmers. This includes basic types, strings, immutable types, and immutable collections of immutable types. If an object state can be changed, the value is not a constant.
+2. Constant names should contain only uppercase letters separated by underscores. They should have a `val` or `const val` (`const` should be used only with primitive types) modifier to make them final (immutable) explicitly. In most cases, if you need to specify a constant value, then you need to create it with the `const val` modifier. Note that not all `val` variables are constants.
 
-2. Constant names should contain only uppercase letters separated by underscores. They should have a val or const val modifier to explicitly make them final. In most cases, if you need to specify a constant value, then you need to create it with the "const val" modifier. Note that not all `val` variables are constants.
-3. Objects that have immutable content, such as `Logger` and `Lock`, can be in uppercase as constants or have camel case as regular variables.
+3. Objects with immutable content, such as `Logger` and `Lock`, can be in uppercase as constants or have camel case as regular variables.
 
 4. Use meaningful constants instead of `magic numbers`. SQL or logging strings should not be treated as magic numbers, nor should they be defined as string constants.
+
 Magic constants like `NUM_FIVE = 5` or `NUM_5 = 5` should not be treated as constants. This is because mistakes will easily be made if they are changed to `NUM_5 = 50` or 55.
 These constants typically represent business logic values, such as measures, capacity, scope, location, tax rate, promotional discounts, and power base multiples in algorithms.
 You can avoid using magic numbers with the following method:
 - Using library functions and APIs. For example, instead of checking that `size == 0`, use `isEmpty()` function. To work with `time`, use built-ins from `java.time API`.
-- Enumerations can be used to name patterns. Refer to [Recommended usage scenario for enumeration in 3.9](#c3.9)
+- Enumerations can be used to name patterns. Refer to [Recommended usage scenario for enumeration in 3.9](#c3.9).
 
 **Invalid example**: 
 
@@ -194,7 +194,7 @@ const val String APPLICATION_NAME = "Launcher";
 ### <a name="c1.6"></a> 1.6 Non-constant fields (variables)
 ### <a name="r1.6.1"></a> Rule 1.6.1: Non-constant field name
 Non-constant field names should use camel case and start with a lowercase letter.
-A local variable cannot be treated as a constant even if it is final and immutable. Therefore, it should not use the preceding rules. Names of collection type variables (sets, lists, etc.) should contain plural nouns.
+A local variable cannot be treated as constant even if it is final and immutable. Therefore, it should not use the preceding rules. Names of collection type variables (sets, lists, etc.) should contain plural nouns.
 For example: `var namesList: List<String>`
 
 Names of non-constant variables should use `lowerCamelCase`. The name of the final immutable field used to store the singleton object can use the same camel case notation.
@@ -214,7 +214,7 @@ val mutableCollection: MutableSet<String> = HashSet()
 
 ### <a name="r1.6.2"></a> Rule 1.6.2: Boolean variable names with negative meaning
 
-Avoid using Boolean variable names with negative meaning. When using a logical operator and name with negative meaning, the code may be difficult to understand, which is referred to as the "double negative".
+Avoid using Boolean variable names with a negative meaning. When using a logical operator and name with negative meaning, the code may be difficult to understand, which is referred to as the "double negative".
 For instance, it is not easy to understand the meaning of !isNotError.
 The JavaBeans specification automatically generates isXxx() getters for attributes of Boolean classes.
 However, not all methods returning Boolean type have this notation.