docs: add refactoring guide

* add `refactoring_guide.md` * link to refactoring_guide.md in contributing.md Authored-by: Joshua Rose <[email protected]>
H4ppy-04 · May 30, 2023 · 683ca70 · 683ca70
1 parent 251dfa5
commit 683ca70
Show file tree

Hide file tree

Showing 4 changed files with 69 additions and 1 deletion.
diff --git a/docs/source/contributing.md b/docs/source/contributing.md
@@ -5,7 +5,7 @@ Contributions are welcome and highly appreciated and as such, guidelines are not
 
 This project is formatted using the [Black](https://pypi.org/project/black/) code style. All formatting is followed as stipulated in python's pep documentation.
 [Black](https://pypi.org/project/black/) is not a part of `requirements.txt` and as such, needs to be installed manually.
-Installation is fairly straightforward and is typically done as follows.
+Installation is fairly straightforward and is typically done as follows. Please refer to the [refactoring guide](refactoring_guide.md) for more information on formatting and refactoring.
 
 ```sh
 exec python -m pip install --user black

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -8,5 +8,6 @@ Contents
    releases.md
    contributing.md
    blog.rst
+   refactoring_guide.md
    documentation.rst
    license.md
diff --git a/docs/source/refactoring_guide.md b/docs/source/refactoring_guide.md
@@ -0,0 +1,53 @@
+# Refactoring Guide
+
+Welcome to the Refactoring Guide for Urban. This guide outlines the goals, principles, and best practices for refactoring within Urban. By following these guidelines, we aim to improve the codebase's readability, maintainability, and overall quality.
+
+## Goals
+
+Refactoring plays a crucial role in Urban's success. The primary objectives of our refactoring efforts include:
+
+- Enhancing code readability and maintainability
+- Reducing complexity and improving code organization
+- Optimizing performance and efficiency
+- Ensuring adherence to clean code principles and coding conventions
+- Enabling future scalability and extensibility
+
+## Refactoring Principles
+
+To achieve our refactoring goals, we follow these key principles:
+
+1. **Keep it readable**: Write code that is easy to understand and follow. Use meaningful and descriptive variable names, functions, and classes. Apply consistent indentation and formatting, adhering to the `PEP 8` style guide.
+
+2. **Eliminate duplication**: Remove code duplication to improve maintainability and reduce the risk of inconsistencies. Identify common patterns and extract reusable functions or classes.
+
+3. **Simplify and clarify**: Break down complex logic into smaller, more manageable components. Aim for single responsibility and modular design. Favor simplicity and clarity over unnecessary complexity.
+
+4. **Optimize performance**: Identify performance bottlenecks and apply appropriate optimizations. Use efficient algorithms, data structures, and caching strategies. Profile and measure the impact of changes to ensure performance improvements.
+
+5. **Test-driven refactoring**: Maintain a comprehensive suite of unit tests to validate the functionality of our codebase. Write tests that cover critical scenarios, and ensure they pass before and after refactoring.
+
+## Refactoring Process
+
+Follow these steps to execute a successful refactoring iteration:
+
+1. **Identify areas for improvement**: Analyze the codebase and identify areas that can benefit from refactoring. Look for code smells, complex sections, duplicated code, or performance bottlenecks.
+
+2. **Plan and prioritize**: Prioritize refactoring tasks based on their impact and urgency. Break down larger refactoring efforts into smaller, manageable steps.
+
+3. **Execute refactoring incrementally**: Refactor small, isolated sections at a time. Validate each refactoring step by running tests to ensure existing functionality is maintained.
+
+4. **Validate and review**: Review the refactored code with your team. Conduct code reviews to ensure adherence to refactoring principles and coding standards. Seek feedback and iterate as necessary.
+
+5. **Track and measure**: Measure the impact of refactoring efforts. Monitor metrics such as code complexity, test coverage, and performance benchmarks to assess the improvements achieved.
+
+## Additional Resources
+
+Explore these additional resources to deepen your understanding of refactoring:
+
+- [Clean Code: A Handbook of Agile Software Craftsmanship](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882) by Robert C. Martin
+- [Refactoring: Improving the Design of Existing Code](https://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672) by Martin Fowler
+- [Effective Python: 50 ways to write better Python](https://www.amazon.com/Effective-Python-Specific-Software-Development/dp/0134853989) by Brett Slatkin
+
+Remember, refactoring is an ongoing process. Continuously strive to improve the codebase and promote clean code practices within Urban.
+
+Let's make our codebase cleaner, more maintainable, and a joy to work with!
diff --git a/pyrightconfig.json b/pyrightconfig.json
@@ -0,0 +1,14 @@
+{
+  "include": [
+    "src/*.py"
+  ],
+  "exclude": [
+    "tests/**/*.py",
+    "tests/*/*.py",
+	"tests/unit/*.py",
+	"tests/integration/*.py",
+	"tests/*.py",
+	"tests/"
+  ]
+}
+