Contains codestyle configuration for:
- IDEA
- Eclipse
- VSCode
And some reference examples (which won't compile so don't even try) to help refine the style properly in supported environments.
The reference examples should reflect the desired format. The IDE configurations may not support or respect this, which is okay while we're developing the format and auto-formatters.
Also contains a set of checkstyle and pmd rules that can be used to enforce code formatting/quality standards as part of the build. Usage/release documentation here.
We want to present a unified approach to code styling across our entire suite of development efforts, automating away the need to respond to deviations during integration of code from a large group of developers, both within and outside of the Sonatype Organization.
All of the development environments used by developers contributing to Sonatype code should be applying the same agreed upon formatting rules consistently, so that we don't spend needless time aligning these rules along with the more substantial (and important!) logical changes we make on a daily basis.
- Any change to existing rules should be discussed and agreed upon by the larger group before implementation. Minimally this should result in a mail to the development group with some minimal time for feedback.
- Any noted deviation between development environments should result in the scheduling of work to correctly align with agreed upon standard.
See the Intellij documentation.
See the eclipse documentation for how to import the files into your IDE. In addition, html indentation settings are not exported, but can be set to 2 spaces from Preferences -> Web -> HTML Files -> Editor -> "Indent using spaces". Screenshot of the eclipse config here.
Import sonatype-visualstudio-settings.xml using Tools -> Import and Export Settings...
Import sonatype-visualstudio-resharper-settings.xml using ReSharper -> Options... -> Manage... -> Import and Export -> Import from file...
VSCode uses Eclipse formatter settings. To import them clone this repository locally and use path to it in the settings.
- Install Java Extension Pack
- Configure Java formatter to use Eclipse settings. You need to specify the name of the profile as well (Sonatype).
- Disable indentation guessing and set it to be forced to 2.
- Change import order and star thresholds
- Disable online services such as telemetry and natural language search. Those features may send portions of what you have typed to Microsoft servers, which we would like to avoid. Some extensions may also include online services, please review all the settings in the Settings UI visible with the
@tag:usesOnlineServices
filter.
All settings required as a JSON snippet (make sure to fix the local path):
{
"java.format.settings.url": "/path/to/local/codestyle/sonatype-eclipse.xml",
"java.format.settings.profile": "Sonatype",
"editor.detectIndentation": false,
"editor.tabSize": 2,
"java.sources.organizeImports.starThreshold": 100,
"java.sources.organizeImports.staticStarThreshold": 10,
"java.completion.importOrder": [
"java",
"javax",
"javafx",
"com.sonatype",
"org.sonatype",
"",
"#"
],
"files.exclude": {
"**/.classpath": true,
"**/.project": true,
"**/.settings": true,
"**/.factorypath": true
},
"workbench.enableExperiments": false,
"telemetry.enableTelemetry": false,
"workbench.settings.enableNaturalLanguageSearch": false
}
120 column right margin
2 space indent for ALL formats
Preferences -> Editor -> General [ On Save: Ensure every saved file ends with a line break ]
Order:
- java
- javax
- javafx
- com.sonatype
- org.sonatype
- other
- static
Wildcard thresholds:
- 100 non-static
- 10 static
Has similarities with "The Elements of Java Style" (book), Google and Eclipse styles with some minor changes for clarity and readability:
- Class/intf/enum declarations are multiline
- if/try/while blocks have new-lines after '}'
Some minor differences between IDEA and Eclipse configurations are unavoidable. The configurations here try to get as close as possible, though if each time a file is reformatted there could be additional noise and thus such operation should generally be avoided. To avoid this pain recommend that reformat entire sources to normalize once, then format discrete blocks where appropriate.
There is some crude support to use Eclipse formatter from IDEA. Unfortunately the Eclipse formatter is not quite as smart as the IDEA formatter in some/many places. The support also seems to have some strange additional configuration for import handling, etc which is not ideal.
It should be possible to craft separate configurations which are mostly compatible and thus avoid most noise if reformatting is done in a sane manner.
DO NOT reformat entire codebases, but reformat as sources are touched to normalize. Or normalize and sanitize one by one, as the code formatters (IDEA or Eclipse) tend to create some formats which can and SHOULD be manually cleaned up, else the code will end up LESS readable.
Follows "Google Javascript Style Guide" with 2 space indents to conform with Java code. Note that IDEA styles import at a global level such that sonatype-idea.xml will import both Java and Javascript style conventions.
Follow docs.scala-lang.org/style. See some differences from Java.
Note that versions prior to 16 will work with Java 8 projects. Versions starting with 17 are intended for use on Java 11 and later projects.
After merging changes to the Checkstyle or PMD rulesets, a main snapshot build will run here. Ensure that passes, then run the release job here. After building a new release, update any builds to use new rule versions as appropriate
Checkstyle
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>3.6.0</version>
<configuration>
<consoleOutput>true</consoleOutput>
<configLocation>sonatype/checkstyle-configuration.xml</configLocation>
<includeTestSourceDirectory>true</includeTestSourceDirectory>
</configuration>
<executions>
<execution>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.sonatype</groupId>
<artifactId>checkstyle-checks</artifactId>
<version>20</version>
</dependency>
</dependencies>
</plugin>
PMD
<plugin>
<artifactId>maven-pmd-plugin</artifactId>
<version>3.10.0</version>
<configuration>
<linkXRef>false</linkXRef>
<printFailingErrors>true</printFailingErrors>
<includeTests>true</includeTests>
<rulesets>
<ruleset>pmd-ruleset/ruleset.xml</ruleset>
</rulesets>
</configuration>
<executions>
<execution>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.sonatype</groupId>
<artifactId>pmd-ruleset</artifactId>
<version>3</version>
</dependency>
</dependencies>
</plugin>