Merge pull request #3 from goatbytes/develop

V. 1.0.0

README.md

@@ -1,4 +1,4 @@
-# GoatStyles by GoatBytes.IO`() {`
+# [GoatStyles][GS] by [GoatBytes.IO][GB]`() {`
 
 ## Introduction
 
@@ -36,7 +36,7 @@ development environments, catering to the diverse needs of the software developm
 ### Repository Structure
 
 The GoatStyles style guides are meticulously documented in Markdown and located within the 
-[`docs/styles`](docs/styles) directory of the repository.
+[`docs/styles`](docs/lang) directory of the repository.
 
 ## How to Contribute
 
@@ -102,13 +102,14 @@ Python version by running `python --version` in your terminal.
 
 ## License
 
-[GoatStyles][GoatStylesRepo] © 2024 by [GoatBytes.IO][GoatBytes.IO] is licensed under [Attribution-ShareAlike 4.0 International][LicenseUrl]
+[GoatStyles][GH] is licensed under [Attribution-ShareAlike 4.0 International][LICENSE]
 
 # `};`
 
-[GoatBytes.IO]: https://goatbytes.io
-[GoatStylesRepo]: https://github.com/goatbytes/GoatStyles
-[LicenseUrl]: https://creativecommons.org/licenses/by-sa/4.0/
+[GS]: https://styles.goatbytes.io
+[GB]: https://goatbytes.io
+[GH]: https://github.com/goatbytes/GoatStyles
+[LICENSE]: https://creativecommons.org/licenses/by-sa/4.0/
 [CLA]: https://forms.gle/J5iqyH4hrHQQDfUCA
 
 <!-- Logo URLs -->

docs/assets/cards/languages.json

@@ -1,62 +1,62 @@
 [
   {
     "title": "C++",
-    "url": "styles/cpp.md",
+    "url": "lang/cpp.md",
     "image": "assets/img/cplusplus.svg"
   },
   {
     "title": "C#",
-    "url":  "styles/csharp.md",
+    "url":  "lang/csharp.md",
     "image": "assets/img/csharp.svg"
   },
   {
     "title": "Dart",
-    "url":  "styles/dart.md",
+    "url":  "lang/dart.md",
     "image": "assets/img/dart.svg"
   },
   {
     "title": "Go",
-    "url":  "styles/go.md",
+    "url":  "lang/go.md",
     "image": "assets/img/go.svg"
   },
   {
     "title": "Java",
-    "url":  "styles/java.md",
+    "url":  "lang/java.md",
     "image": "assets/img/java.svg"
   },
   {
     "title": "JavaScript",
-    "url":  "styles/javascript.md",
+    "url":  "lang/javascript.md",
     "image": "assets/img/javascript.svg"
   },
   {
     "title": "Kotlin",
-    "url":  "styles/kotlin.md",
+    "url":  "lang/kotlin.md",
     "image": "assets/img/kotlin.svg"
   },
   {
     "title": "Objective-C",
-    "url":  "styles/objc.md",
+    "url":  "lang/objective-c.md",
     "image": "assets/img/objective-c.svg"
   },
   {
     "title": "Python",
-    "url":  "styles/python.md",
+    "url":  "lang/python.md",
     "image": "assets/img/python.svg"
   },
   {
     "title": "Rust",
-    "url":  "styles/rust.md",
+    "url":  "lang/rust.md",
     "image": "assets/img/rust.svg"
   },
   {
     "title": "Swift",
-    "url":  "styles/swift.md",
+    "url":  "lang/swift.md",
     "image": "assets/img/swift.svg"
   },
   {
     "title": "TypeScript",
-    "url":  "styles/typescript.md",
+    "url":  "lang/typescript.md",
     "image": "assets/img/typescript.svg"
   }
 ]

docs/assets/js/app.js

@@ -5,10 +5,4 @@ console.log(`
          | )  _ \\ \\
         / / \`\`   w w
        w w
-`);
-
-document.addEventListener("DOMContentLoaded", function() {
-    document.querySelectorAll('.good-code').forEach(e => {
-        console.log(e);
-    });
-});
+`);

docs/styles/foundation.md → docs/foundation.md

@@ -103,7 +103,7 @@ conventions.
 ### Whitespace
 
 - Include a space before parentheses and the left brace `{` for control structures
-- (`if`, `for`, `while`, etc.).
+  (`if`, `for`, `while`, etc.).
 - Include Space around all operators (`->`, `=`, `+`, `*`, `/`, `>>`, etc.), except before unary and
   range operators.
 - Include a space before `else`, `catch`, and `finally` keywords.
@@ -153,8 +153,7 @@ Use blank lines strategically to separate logical blocks of code for better read
  * - Consistent spacing for parameter lists and constructor arguments.
  * - Doc comments with aligned descriptions.
  */
-
-class WellFormattedCode { // (1)!
+class WellFormattedCode/*(1)!*/ {
 public:
     /**
      * This method calculates the factorial of a given positive integer.

docs/index.md

@@ -1,14 +1,22 @@
 # GoatStyles — Professional Code Style Guides
 
-:wave: Welcome to our platform for professional code style guides, where we strive to uphold the highest standards of software engineering.
+:wave: Welcome to our platform for professional code style guides, where we strive to uphold the
+highest standards of software engineering.
 
-In the realm of code style guides, we understand that opinions vary, and decisions often balance between necessity and subjectivity. However, amidst this diversity of perspectives, one principle remains paramount: consistency. Just as collaboration and cohesion within teams foster unity, a unified code style promotes clarity amidst diversity, enhancing comprehension and simplifying maintenance.
-
-By adhering to a consistent style, we aim to accelerate understanding and streamline maintenance, enabling engineers to navigate complex systems with ease. Championing accessibility and openness, we advocate for code that remains universally understandable, transcending individual preferences to embrace standards of clarity and coherence.
+In the realm of code style guides, we understand that opinions vary, and decisions often balance
+between necessity and subjectivity. However, amidst this diversity of perspectives, one principle
+remains paramount: __consistency__. By adhering to a consistent style, developers can enhance
+readability, maintainability, and collaboration within their codebases. The 
+[Foundational Code Standards](foundation.md) serve as a universal guideline, ensuring that
+language-specific style guides uphold these ideals of clarity and cohesiveness.
 
 ## Language-Specific Style Guidelines
 
-[cards cols=6 (./docs/assets/cards/languages.json)]
+[cards cols=4 (./docs/assets/cards/languages.json)]
 
 /// admonition |
-Each guideline outlined in our style guides is carefully curated to promote best practices and address common pitfalls specific to the respective programming languages. By following these guidelines, developers can write code that is not only consistent but also optimized for readability and maintainability.
+Each guideline outlined in our style guides is carefully curated to promote best practices and
+address common pitfalls specific to the respective programming languages. By following these
+guidelines, developers can write code that is not only consistent but also optimized for readability
+and maintainability.
+///

docs/styles/cpp.md → docs/lang/cpp.md

@@ -6,20 +6,19 @@ C++-specific considerations.
 [//]: # (@formatter:off)
 /// admonition |
     type: abstract
-[Foundational Code Standards][fnd]{:target="_blank"} provide the foundation, this guide extends them for C++.
+[Foundational Code Standards][FOUNDATION]{:target="_blank"} provide the foundation, this guide extends them for C++.
 ///
 [//]: # (@formatter:on)
 
 ## Formatting
 
-While our C++ formatting guidelines follows the [Foundational Code Standards][fnd-formatting] for
-formatting, summarized below:
+The formatting rules for C++ adhere to our foundational [formatting standards][FORMATTING] with the
+following exceptions:
 
 - **Indentation:** Use 4 spaces for indentation.
 - **Continuation indent:** Use 8 spaces for line continuations.
 
-Otherwise, adhere to the general formatting guidelines outlined in the foundational standards and
-briefly summarized below.
+Otherwise, follow the conventions outlined in the foundational standards, summarized below:
 
 - **Line Length:** Aim for 100 characters, but allow flexibility for readability.
 - **Whitespace:** Use spaces around operators, parentheses, braces, colons, commas, and keywords for
@@ -34,99 +33,70 @@ briefly summarized below.
 Remember, these are guidelines; adapt them for your project's needs while keeping readability in focus.
 ///
 
-/// details | Formatted C++ Example Code
-    type: example
-```cpp
-#include <iostream>
-#include <vector>
+## Naming Conventions
 
-// Attributes used for demonstration
-[[nodiscard]] class Example {
-public:
-    // Constructor with initializer list
-    Example(int x, int y) : x_(x), y_(y) {}
+The naming conventions for Kotlin adhere to our foundational [naming conventions][NAMING]
+with no exceptions.
 
-    // Method declaration
-    void doSomething();
+- **PascalCase** for classes, interfaces, enums (definitions).
+- **camelCase** for functions, variables, properties.
+    - Prefix booleans with `is` or `has` for clarity.
+- **UPPER_SNAKE_CASE** for constants.
+- **lowercase** package names, concatenated words (avoid underscores).
 
-private:
-    int x_;
-    int y_;
-
-    // Inner class
-    class Inner {
-    public:
-        void innerMethod() {
-            std::cout << "Inside innerMethod" << std::endl;
+---
+
+**Example**
+
+```cpp
+/**
+ * This class demonstrates proper code formatting following the specified style guide.
+ *
+ * **Formatting Rules:**
+ * - 4 spaces for indentation (C++ exception).
+ * - 8 spaces for continuation lines (C++ exception).
+ * - Max line length of 100 characters.
+ * - Spaces around operators, control structures, and keywords.
+ * - K&R brace style.
+ * - Consistent spacing for parameter lists and constructor arguments.
+ * - Doc comments with aligned descriptions.
+ */
+class WellFormattedCode/*(1)!*/ {
+public:
+    /**
+     * This method calculates the factorial of a given positive integer.
+     *
+     * @param n The non-negative integer for which to calculate the factorial.
+     * @return  The factorial of n, or throws an std::invalid_argument exception if n is negative.
+     * @throws std::invalid_argument If the provided number (n) is negative.
+     */
+    static long calculateFactorial/*(2)!*/(int n) {
+        if (n < 0) {// (3)!
+            throw std::invalid_argument("Factorial is not defined for negative numbers.");
         }
-    };
 
-    // Example of a static method
-    static void staticMethod() {
-        if (true) {
-          std::cout << "Static method called" << std::endl;
+        long result = 1;
+        for (int i = 2; i <=/*(4)!*/ n; ++i) {
+            result *= i;
         }
+        return result;
     }
 };
-
-void Example::doSomething() {
-    Inner inner;
-    inner.innerMethod();
-
-    int sum = x_ + y_; // Demonstrating space around operator
-    std::cout << "Sum: " << sum << std::endl;
-
-    // For loop demonstrating continuation indent and spaces
-    for (int i = 0; i < 10; i += 2) {
-        std::cout << i << " ";
-    }
-    std::cout << std::endl;
-
-    // If-else structure
-    if (sum > 10) {
-        std::cout << "Sum is greater than 10" << std::endl;
-    } else {
-        std::cout << "Sum is 10 or less" << std::endl;
-    }
-
-    // Try-catch block
-    try {
-        throw std::runtime_error("Example exception");
-    } catch (const std::runtime_error& e) {
-        std::cout << "Caught an exception: " << e.what() << std::endl;
-    }
-}
-
-int main() {
-    Example example(5, 8);
-    example.doSomething();
-    Example::staticMethod();
-
-    return 0;
-}
 ```
 
-///
+1.    Class name in PascalCase with a doc comment.
+2.    Method name in camelCase with a doc comment.
+3.    K&R brace style for blocks.
+4.    Proper spacing around operators and control structures.
 
 [//]: # (@formatter:on)
 
-## Naming Conventions
-
-The naming conventions for Kotlin adhere to our [Foundational Code Standards][fnd-naming]
-with no exceptions.
-
-- **PascalCase** for classes, interfaces, enums (definitions).
-- **camelCase** for functions, variables, properties.
-    - Prefix booleans with "is" or "has" for clarity.
-- **UPPER_SNAKE_CASE** for constants.
-- **lowercase** package names, concatenated words (avoid underscores).
-
-[//]: # (TODO: Add good/bad examples for naming conventions)
+---
 
 ## Documentation and Comments
 
-Refer to the [Foundational Code Standards][fnd-docs] for general commenting and documentation
-guidelines.
+Refer to the [Foundational Documentation and Comments Standards][DOCS] for general commenting and 
+documentation guidelines.
 
 ### Documentation Example
 
@@ -144,7 +114,7 @@ guidelines.
  * **Usage Example:**
  * `
  * Goat billy("Billy", 5);
- * std::cout << (billy.isHappy(3) ? "True" : "False") << std::endl; // Outputs "True" or "False" based on the number of meals.
+ * std::cout << (billy.isHappy(3) ? "True" : "False") << std::endl;
  * `
  * 
  * @author Author's Name
@@ -181,12 +151,6 @@ private:
     int age_;
 };
 
-int main() {
-    Goat billy("Billy", 5);
-    std::cout << "Billy is " << (billy.isHappy(3) ? "happy" : "not happy") << std::endl;
-
-    return 0;
-}
 ```
 
 ## Idioms and Best Practices
@@ -258,9 +222,9 @@ resources:
   aspects of C++ programming, from basics to advanced topics.
 
 [//]: # (@formatter:off)
-[fnd]: foundation.md
-[fnd-formatting]: foundation.md#formatting
-[fnd-naming]: foundation.md#naming-conventions
-[fnd-docs]: foundation.md#documentation-and-comments
+[FOUNDATION]: ../foundation.md
+[FORMATTING]: ../foundation.md#formatting
+[NAMING]: ../foundation.md#naming-conventions
+[DOCS]: ../foundation.md#documentation-and-comments
 [Effective Modern C++]: https://www.oreilly.com/library/view/effective-modern-c/9781491908419/
 [//]: # (@formatter:on)