You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(java): clarify Sonar, Java version, and code-style guidance (#338)
* 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 <[email protected]>
Signed-off-by: Ashley Childress <[email protected]>
* 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 <[email protected]>
Signed-off-by: Ashley Childress <[email protected]>
---------
Signed-off-by: Ashley Childress <[email protected]>
Copy file name to clipboardExpand all lines: instructions/java.instructions.md
+41-24Lines changed: 41 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,8 +7,24 @@ applyTo: '**/*.java'
7
7
8
8
## General Instructions
9
9
10
-
- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle)
11
-
into their project setup. If yes, provide guidance on tool selection and configuration.
10
+
- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle) into their project setup.
11
+
- If yes, document a recommended static-analysis setup.
12
+
- Prefer SonarQube/SonarCloud (SonarLint in IDE + `sonar-scanner` in CI).
13
+
- Create a Sonar project key.
14
+
- Store the scanner token in CI secrets.
15
+
- Provide a sample CI job that runs the scanner.
16
+
- If the team declines Sonar, note this in the project README and continue.
17
+
- If Sonar is bound to the project:
18
+
- Use Sonar as the primary source of actionable issues.
19
+
- Reference Sonar rule keys in remediation guidance.
20
+
- If Sonar is unavailable:
21
+
- Perform up to 3 troubleshooting checks:
22
+
1. Verify project binding and token.
23
+
2. Ensure SonarScanner runs in CI.
24
+
3. Confirm SonarLint is installed and configured.
25
+
- If still failing after 3 attempts:
26
+
- Enable SpotBugs, PMD, or Checkstyle as CI fallbacks.
27
+
- Open a short tracker issue documenting the blocker and next steps.
12
28
- 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.
13
29
- Address code smells proactively during development rather than accumulating technical debt.
14
30
- Focus on readability, maintainability, and performance when refactoring identified issues.
@@ -33,28 +49,29 @@ applyTo: '**/*.java'
33
49
- Use nouns for classes (`UserService`) and verbs for methods (`getUserById`).
|`S107`| Methods should not have too many parameters | Refactor into helper classes or use builder pattern. |
51
-
|`S121`| Duplicated blocks of code should be removed | Consolidate logic into shared methods. |
52
-
|`S138`| Methods should not be too long | Break complex logic into smaller, testable units. |
53
-
|`S3776`| Cognitive complexity should be reduced | Simplify nested logic, extract methods, avoid deep `if` trees. |
54
-
|`S1192`| String literals should not be duplicated | Replace with constants or enums. |
55
-
|`S1854`| Unused assignments should be removed | Avoid dead variables—remove or refactor. |
56
-
|`S109`| Magic numbers should be replaced with constants | Improves readability and maintainability. |
57
-
|`S1188`| Catch blocks should not be empty | Always log or handle exceptions meaningfully. |
52
+
### Common Bug Patterns
53
+
54
+
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.
55
+
56
+
- Resource management — Always close resources (files, sockets, streams). Use try-with-resources where possible so resources are closed automatically.
57
+
- Equality checks — Compare object equality with `.equals()` or `Objects.equals(...)` rather than `==` for non-primitives; this avoids reference-equality bugs.
58
+
- Redundant casts — Remove unnecessary casts; prefer correct generic typing and let the compiler infer types where possible.
59
+
- Reachable conditions — Avoid conditional expressions that are always true or false; they indicate bugs or dead code and should be corrected.
60
+
61
+
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.
62
+
63
+
### Common Code Smells
64
+
65
+
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.
66
+
67
+
- Parameter count — Keep method parameter lists short. If a method needs many params, consider grouping into a value object or using the builder pattern.
68
+
- Method size — Keep methods focused and small. Extract helper methods to improve readability and testability.
69
+
- Cognitive complexity — Reduce nested conditionals and heavy branching by extracting methods, using polymorphism, or applying the Strategy pattern.
70
+
- Duplicated literals — Extract repeated strings and numbers into named constants or enums to reduce errors and ease changes.
71
+
- Dead code — Remove unused variables and assignments. They confuse readers and can hide bugs.
72
+
- Magic numbers — Replace numeric literals with named constants that explain intent (e.g., MAX_RETRIES).
73
+
74
+
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.
0 commit comments