docs: added an article about avoiding a global resource file

Co-authored-by: gohierf <[email protected]>

Author: d-biehl

docs/04_tip_and_tricks/avoiding_a_global_resource_file.md

@@ -0,0 +1,96 @@
+# Avoiding a Global Resource File
+
+When organizing your suite, tests, resources and libraries in a Robot Framework project, it may seem attractive to consolidate all libraries and resources into one global file - for example, a `Keywords.resource` file - and then include only this single file in every suite or resource. At first glance, this strategy appears to streamline the setup by reducing the number of explicit imports. However, while it may simplify the initial configuration, this approach often leads to a host of challenges later on.
+
+## Why is it not a good idea?
+
+- **Circular Dependencies**: Importing one global file into multiple keyword resource files can lead to circular dependencies. RobotCode will issue warnings in these cases, indicating that a file is already imported or that a circular reference has been detected. Beyond these warnings, circular dependencies are a red flag for poor design. They complicate dependency management, hinder refactoring efforts, and obscure the overall structure of the project. Additionally, circular references indicate that components are too tightly coupled, which makes the system less modular and more prone to cascading errors when changes are made.
+
+- **Risk of Overwriting Keywords or Variables**: Centralizing all resources increases the likelihood of naming collisions. With many keywords and variables defined in one file, accidental overwrites become more probable, making debugging more challenging and causing unpredictable test outcomes.
+
+- **Performance Issues**: Robot Framework, and consequently RobotCode, iterates through the entire list of known keywords for every keyword call, checking each one to see if it matches the call. This process becomes particularly time-consuming when using keywords with embedded arguments, where regular expressions are involved rather than simple string comparisons. A large global resource file filled with rarely-used elements can therefore significantly slow down keyword resolution, especially in larger projects.
+
+- **Decreased Maintainability**: When hundreds or even thousands of resources reside in a single file, it becomes increasingly difficult for test writers to locate the relevant keywords or variables. This not only hinders productivity but also adds unnecessary complexity to both test creation and maintenance.
+
+- **Creation of Unnecessary References**: Relying on a centralized file creates redundant links across your project, making it harder to track resource usage. These unnecessary references increase the risk of errors during updates or refactoring.
+
+## Documentation Through Suite Settings
+
+Library and resource declarations in the suite settings serve as both configuration and vital documentation. Test suites and test cases are not merely executable source code; they are also a critical part of your project's overall documentation. By explicitly declaring which libraries and resources are required—for instance, for handling login processes, customer management, and database validations—you provide clear insight into the functional areas under test. This explicit mapping not only improves maintainability but also communicates intent.
+
+When someone reads the suite settings, they understand not only how the tests run but also which aspects of the application are considered critical. For example:
+
+```robot
+*** Settings ***
+Library   LoginLibrary
+Resource  CustomerManagement.resource
+Resource  DatabaseValidation.resource
+```
+
+This declaration tells the reader that the test suite is focused on specific areas of the application. It offers an immediate understanding of the suite's scope, serving as a form of living documentation. As such, tests become more than just code—they become an integral part of your project's documentation, helping new team members, stakeholders, and automated systems quickly grasp what parts of the application are being validated.
+
+## Limitations in Import and Package Management
+
+It is also worth noting that Robot Framework, in its current form, lacks a robust import or package management system. The framework does not complain if resources or libraries are imported multiple times, which might seem convenient at first. However, this behavior can lead to issues—for instance, when the same library is imported with different parameters, Robot Framework may simply overwrite the previous instance, resulting in unpredictable behavior. The concepts of public versus private imports and a proper package management system for Robot Framework are regular topics in roadmap discussions. One can only hope that future versions will address these limitations to better support modular and reliable test architectures.
+
+## Clean Code Considerations
+
+Adhering to clean code principles is essential for building maintainable, readable, and scalable projects. A modular approach offers several advantages:
+
+- **Separation of Concerns**: Dividing resources into logically grouped files ensures that each file has a clear, focused purpose. This separation makes the codebase easier to understand and maintain.
+- **Enhanced Readability**: A smaller, purpose-driven file structure improves readability. Developers can quickly locate and modify only the necessary parts without wading through irrelevant code.
+- **Simplified Dependency Management**: Reducing the number of references between files decreases coupling. This clear separation limits the impact of changes, making your project more resilient to modifications over time.
+- **Ease of Refactoring**: With resources organized into well-defined modules, refactoring becomes more straightforward. Developers can update or replace specific parts of the project without unintended side effects on unrelated components.
+
+## What is the Better Approach?
+
+The recommended solution is to **modularize your resources**:
+
+- **Keep the Global File Minimal**: Limit the global resource file to only the libraries and resources that are truly needed across all test cases and keyword files.
+- **Import Only What’s Needed**: Instead of centralizing everything in a single file, selectively import only the necessary resources into each test case or keyword file.
+- **Organize Resources into Logical Groups**: Structure your project by separating resources into distinct files based on their function. For example:
+  - Business-specific (functional) keywords
+  - Technical keywords (e.g., those dealing with databases, APIs, or UI interactions)
+
+This modular approach not only helps eliminate issues like circular dependencies and performance bottlenecks but also enhances maintainability and clarity. It ensures that suite settings serve as clear documentation for the parts of the application under test.
+
+### What if Restructuring is Not an Option?
+
+If modifying your project structure is not possible, consider mitigating potential issues by managing the warnings provided by your development environment. You can suppress warnings related to circular dependencies and redundant imports either on a per-file basis or globally. For global suppression, your development environment (e.g., VS Code) can be configured to ignore specific warning names encountered during the analysis of import statements. These warning names include:
+
+- `PossibleCircularImport`: Indicates a potential circular dependency that may not be immediately evident.
+- `CircularImport`: Signals that a circular dependency has been definitively detected.
+- `ResourceAlreadyImported`: Warns that a resource file is being imported more than once.
+- `VariablesAlreadyImported`: Alerts that a variables file has been imported multiple times.
+- `LibraryAlreadyImported`: Notifies that a library has already been imported, which can be problematic if imported with different parameters.
+
+- **Suppress Warnings Globally**: Alternatively, configure your development environment (e.g., VS Code) to disable these warnings project-wide by adjusting the settings.
+
+  In VS Code you can add the following to your `settings.json`:
+
+  ```json
+  "robotcode.analysis.diagnosticModifiers.ignore": [
+      "PossibleCircularImport",
+      "CircularImport",
+      "ResourceAlreadyImported",
+      "VariablesAlreadyImported",
+      "LibraryAlreadyImported"
+  ]
+  ```
+
+  Or you can also use a [`robot.toml`](http://localhost:5173/03_reference/config) file and add the following contents:
+
+  ```toml
+  [tool.robotcode-analyze.modifiers]
+  ignore = [
+      "PossibleCircularImport",
+      "CircularImport",
+      "ResourceAlreadyImported",
+      "VariablesAlreadyImported",
+      "LibraryAlreadyImported"
+  ]
+  ```
+
+## Conclusion
+
+While using a single global resource file like **Keywords.resource** may appear to simplify your test setup by reducing the number of imports, it ultimately creates more problems than it solves. Issues such as circular dependencies—flagged by RobotCode warnings and indicative of poor design choices—naming collisions, performance degradation, and decreased maintainability quickly outweigh the initial convenience. Moreover, a modular approach not only adheres to clean code principles but also ensures that your suite settings clearly document the specific components required for each suite. This clarity is vital for understanding which parts of the application—such as login processes, customer management, or database checks—are being tested. A modular resource structure is the optimal solution for avoiding these pitfalls. However, if a centralized file is unavoidable, you can manage the risks by selectively suppressing warnings.