josiadmin/awesome-copilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(java): clarify Sonar, Java version, and code-style guidance (#338)

Browse Source 
* docs(java): clarify Sonar, Java version, and code-style guidance

 - Clarify SonarQube/SonarCloud setup, token handling, and CI scanner steps
 - Add guidance for Records, pattern matching, and `var` usage heuristics
 - Provide fallbacks when static analysis is unavailable and troubleshooting steps
 - Original rules are no longer included in the standard Sonar Way ruleset
 - Remove future dependency on Sonar by prompting to use when integrated or available
 - If not, the agent will now read Sonar rules as part of its analysis
 - Removed obsolete and redundant sections on Java version and code style

Generated-by: GitHub Copilot <github.copilot@github.com>
Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>

* docs(java): improve SonarQube setup instructions readability

 - Break long bullet points into structured sub-bullets for clarity
 - Organize SonarQube troubleshooting steps into numbered sequence
 - Separate fallback tools configuration from main Sonar workflow

Fixes #296
Co-authored-by: GitHub Copilot <github.copilot@github.com>

Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>

---------

Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
This commit is contained in:
Ashley Childress 2025-10-20 19:57:48 -04:00 committed by GitHub
parent ca37fc8d6d
commit bef83321a0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 38 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
instructions/java.instructions.md
View File

@ -7,8 +7,24 @@ applyTo: '**/*.java'
## General Instructions ## General Instructions
- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle) - First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle) into their project setup.
into their project setup. If yes, provide guidance on tool selection and configuration. - If yes, document a recommended static-analysis setup.
- Prefer SonarQube/SonarCloud (SonarLint in IDE + `sonar-scanner` in CI).
- Create a Sonar project key.
- Store the scanner token in CI secrets.
- Provide a sample CI job that runs the scanner.
- If the team declines Sonar, note this in the project README and continue.
- If Sonar is bound to the project:
- Use Sonar as the primary source of actionable issues.
- Reference Sonar rule keys in remediation guidance.
- If Sonar is unavailable:
- Perform up to 3 troubleshooting checks:
1. Verify project binding and token.
2. Ensure SonarScanner runs in CI.
3. Confirm SonarLint is installed and configured.
- If still failing after 3 attempts:
- Enable SpotBugs, PMD, or Checkstyle as CI fallbacks.
- Open a short tracker issue documenting the blocker and next steps.
- If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below. - If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below.
- Address code smells proactively during development rather than accumulating technical debt. - Address code smells proactively during development rather than accumulating technical debt.
- Focus on readability, maintainability, and performance when refactoring identified issues. - Focus on readability, maintainability, and performance when refactoring identified issues.
@ -33,28 +49,29 @@ applyTo: '**/*.java'
- Use nouns for classes (`UserService`) and verbs for methods (`getUserById`). - Use nouns for classes (`UserService`) and verbs for methods (`getUserById`).
- Avoid abbreviations and Hungarian notation. - Avoid abbreviations and Hungarian notation.
### Bug Patterns ### Common Bug Patterns
| Rule ID | Description | Example / Notes | Below are concise, human-readable rules you can apply regardless of which static analysis tool you use. If you run Sonar/SonarLint, the IDE will show the matching rule and location — direct Sonar connections are preferred and should override this ruleset.
| ------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `S2095` | Resources should be closed | Use try-with-resources when working with streams, files, sockets, etc. |
| `S1698` | Objects should be compared with `.equals()` instead of `==` | Especially important for Strings and boxed primitives. |
| `S1905` | Redundant casts should be removed | Clean up unnecessary or unsafe casts. |
| `S3518` | Conditions should not always evaluate to true or false | Watch for infinite loops or if-conditions that never change. |
| `S108` | Unreachable code should be removed | Code after `return`, `throw`, etc., must be cleaned up. |
## Code Smells - Resource management — Always close resources (files, sockets, streams). Use try-with-resources where possible so resources are closed automatically.
- Equality checks — Compare object equality with `.equals()` or `Objects.equals(...)` rather than `==` for non-primitives; this avoids reference-equality bugs.
- Redundant casts — Remove unnecessary casts; prefer correct generic typing and let the compiler infer types where possible.
- Reachable conditions — Avoid conditional expressions that are always true or false; they indicate bugs or dead code and should be corrected.
| Rule ID | Description | Example / Notes | For contributors who *do* use Sonar or SonarLint: the IDE/scan will show the specific rule key (for example, S2095 for resource leaks) and the affected file/line. Use that information to navigate to the exact location, then apply the recommended remediation.
| ------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `S107` | Methods should not have too many parameters | Refactor into helper classes or use builder pattern. | ### Common Code Smells
| `S121` | Duplicated blocks of code should be removed | Consolidate logic into shared methods. |
| `S138` | Methods should not be too long | Break complex logic into smaller, testable units. | These patterns are phrased for humans; they map cleanly to checks in Sonar, SpotBugs, PMD, or Checkstyle but do not require those tools to be useful.
| `S3776` | Cognitive complexity should be reduced | Simplify nested logic, extract methods, avoid deep `if` trees. |
| `S1192` | String literals should not be duplicated | Replace with constants or enums. | - Parameter count — Keep method parameter lists short. If a method needs many params, consider grouping into a value object or using the builder pattern.
| `S1854` | Unused assignments should be removed | Avoid dead variables—remove or refactor. | - Method size — Keep methods focused and small. Extract helper methods to improve readability and testability.
| `S109` | Magic numbers should be replaced with constants | Improves readability and maintainability. | - Cognitive complexity — Reduce nested conditionals and heavy branching by extracting methods, using polymorphism, or applying the Strategy pattern.
| `S1188` | Catch blocks should not be empty | Always log or handle exceptions meaningfully. | - Duplicated literals — Extract repeated strings and numbers into named constants or enums to reduce errors and ease changes.
- Dead code — Remove unused variables and assignments. They confuse readers and can hide bugs.
- Magic numbers — Replace numeric literals with named constants that explain intent (e.g., MAX_RETRIES).
If you run a static analyzer like Sonar or SonarLint — direct Sonar connections are preferred and should override this ruleset. Sonar rule keys are useful for automation and suppression, but they are not required in day-to-day developer guidance.
## Build and Verification ## Build and Verification