docs: rewrite common-misconceptions.md to ASD-STE100 rules - #2035
Conversation
elharo
changed the title
gnodet
left a comment
gnodet
left a comment
There was a problem hiding this comment.
Clean STE rewrite — all hyperlinks and code blocks preserved. Two substantive issues and two minor formatting nits below.
This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.
Claude Code on behalf of Guillaume Nodet
| All fine and dandy. At the same time, you want to avoid any use of Guava. We all know Guava is a direct dependency | ||
| of Guice. This is fine, since as we know, the best practice is to declare all dependencies your code compiles | ||
| against. By not having Guava here, analysis tools will report if code touches Guava as an "undeclared dependency". | ||
| The model code does not directly use Guava. However, Guava is a direct dependency of Guice. |
There was a problem hiding this comment.
"The model code" is not standard Maven/Java terminology. In the Maven ecosystem, "model" has a specific meaning (the POM model, org.apache.maven.model.Model), so "model code" could be misread as referring to the POM model code.
The original said "you want to avoid any use of Guava" — referring to the project's production source code. Consider:
| The model code does not directly use Guava. However, Guava is a direct dependency of Guice. | |
| Your project code does not directly use Guava. However, Guava is a direct dependency of Guice. |
| **Wrong**. As can be seen from above, for runtime graph we leave out "test" scoped | ||
| dependencies. It was true in Maven2, where test graph really was a superset of runtime, | ||
| but this does not stand anymore in Maven3. And this has interesting consequences. Let me show an example: | ||
| **Wrong**. For the runtime graph, Resolver omits the "test" scoped dependencies. This has interesting consequences. The example below shows this. |
There was a problem hiding this comment.
The original stated: "It was true in Maven2, where test graph really was a superset of runtime, but this does not stand anymore in Maven3."
This historical context is important on a page titled "Common Misconceptions" — it explains why people hold this belief (because it was actually true in Maven 2). Without it, the section says "Wrong" but doesn't explain the origin. Consider restoring it:
| **Wrong**. For the runtime graph, Resolver omits the "test" scoped dependencies. This has interesting consequences. The example below shows this. | |
| **Wrong**. In Maven 2, the test graph was a superset of the runtime graph. This is no longer true in Maven 3. For the runtime graph, Resolver omits the "test" scoped dependencies. This has interesting consequences. The example below shows this. |
gnodet
left a comment
gnodet
left a comment
There was a problem hiding this comment.
"model code" → "src/main code" addresses the ambiguity — clearer in context. The Maven 2 historical context (explaining why the misconception exists) is still absent, but this is left to the author's discretion.
This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.
Claude Code on behalf of Guillaume Nodet
|
@elharo Please assign appropriate label to PR according to the type of change. |
2 participants
Rewrite the page to ASD-STE100 Simplified Technical English.
Classification: the whole page is descriptive text.
Changes:
Supersedes the earlier attempt in #2031.