netejant capçaleres

CLAUDE.md

@@ -55,9 +55,15 @@ cmake --build build --clean-first
 
 **Important:** The build directory is `/Users/sergio/Gitea/jaildoctors_dilemma/build` and the output executable is placed in the project root directory.
 
-### Linter (clang-tidy)
+### Static Analysis Tools (Linters)
 
-**IMPORTANT:** Always run the linter on specific files, NOT on the entire project, to avoid long execution times and errors in unrelated files.
+This project uses two complementary static analysis tools for code quality:
+
+#### clang-tidy (Modernization & Best Practices)
+
+**Purpose:** Detects style issues, modernization opportunities, and potential bugs. Best for refactoring and applying C++20 best practices.
+
+**IMPORTANT:** Always run on specific files, NOT on the entire project, to avoid long execution times and errors in unrelated files.
 
 ```bash
 # Analyze a specific file (RECOMMENDED)
@@ -73,7 +79,80 @@ tools/linter/run_clang-tidy.sh --fix source/game/entities/player.cpp
 tools/linter/run_clang-tidy.sh
 ```
 
-**Note:** Running the linter on the entire project can produce errors in files like `defaults.hpp` that are unrelated to your changes. Always target specific files you're working on.
+**Common clang-tidy Checks:**
+- `modernize-*`: C++ modernization (use auto, range-for, etc.)
+- `readability-*`: Code readability improvements
+- `performance-*`: Performance optimizations
+- `bugprone-*`: Potential bug detection
+
+**Known False Positives:**
+- `defaults.hpp`: May report errors in constant definitions
+- `readability-magic-numbers`: Acceptable for game constants (block sizes, speeds, etc.)
+- `cppcoreguidelines-avoid-magic-numbers`: Same as above, acceptable in game code
+
+#### cppcheck (Bug Detection & Memory Safety)
+
+**Purpose:** Detects bugs, memory leaks, undefined behavior, and style issues. Complementary to clang-tidy.
+
+```bash
+# Warning, style, and performance analysis (RECOMMENDED for daily use)
+tools/linter/run_cppcheck.sh -w --path source/game/entities/player.cpp
+
+# Exhaustive analysis (slower, more thorough)
+tools/linter/run_cppcheck.sh -a --path source/game/entities/
+
+# Detect unused functions (whole project analysis)
+tools/linter/run_cppcheck.sh -u
+
+# Analyze entire project with warning level
+tools/linter/run_cppcheck.sh -w
+```
+
+**Output:** Results are saved in `tools/linter/cppcheck-result-*.txt`
+
+**Common cppcheck Checks:**
+- Memory leaks and resource management
+- Null pointer dereferences
+- Buffer overflows and array bounds
+- Uninitialized variables
+- Dead code and unused functions
+
+**Known False Positives:**
+- `unusedFunction`: May report false positives for callback functions or public API methods
+- `passedByValue`: Acceptable for small types like SDL_FRect in game code
+- `constParameter`: Not always applicable for API consistency
+
+#### When to Use Each Tool
+
+| Scenario | Tool | Reason |
+|----------|------|--------|
+| **Daily refactoring** | clang-tidy | Fast, auto-fixable issues |
+| **Before committing** | Both | Comprehensive quality check |
+| **After major changes** | cppcheck -a | Deep bug analysis |
+| **Hunting memory leaks** | cppcheck | Specialized detection |
+| **Code modernization** | clang-tidy --fix | Automatic C++20 upgrades |
+
+#### Best Practices
+
+1. **Run linters after compilation succeeds** - Fix compile errors first
+2. **Analyze specific files** - Faster feedback, avoids unrelated errors
+3. **Review before applying --fix** - Understand changes before accepting
+4. **Context matters** - Game code may legitimately have "magic numbers" for gameplay constants
+5. **Use both tools** - They catch different issues and complement each other
+6. **Check suppressions file** - `tools/linter/cppcheck_suppressions` excludes external/ and system headers
+
+#### Integration with Development Workflow
+
+When refactoring code (especially with `/refactor-class` command):
+1. Make structural changes
+2. **Compile** to verify syntax
+3. **Run clang-tidy** (without --fix) to identify issues
+4. **Run cppcheck -w** to catch bugs
+5. Review and fix legitimate issues
+6. Apply automatic fixes if appropriate
+7. Recompile and test
+
+**Note:** The `/refactor-class` command automatically runs both linters after compilation and provides intelligent analysis of results.
 
 ---