You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2022/11/30 09:08:42 UTC
[maven-site] branch master updated: [MNGSITE-500] clean up code style documentation after adoption of spotless with palantir
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new a238b35f [MNGSITE-500] clean up code style documentation after adoption of spotless with palantir
a238b35f is described below
commit a238b35f8f756d8a28e5a95274f3f9bf6e389dba
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Wed Nov 30 10:08:36 2022 +0100
[MNGSITE-500] clean up code style documentation after adoption of
spotless with palantir
This relates to the changes introduced with [MPOM-349]
---
content/apt/developers/committer-environment.apt | 38 ++-----
content/apt/developers/conventions/code.apt | 129 +++--------------------
2 files changed, 20 insertions(+), 147 deletions(-)
diff --git a/content/apt/developers/committer-environment.apt b/content/apt/developers/committer-environment.apt
index 4d1c84f5..a527e9b0 100644
--- a/content/apt/developers/committer-environment.apt
+++ b/content/apt/developers/committer-environment.apt
@@ -26,11 +26,13 @@
~~ NOTE: For help with the syntax of this file, see:
~~ https://maven.apache.org/doxia/references/apt-format.html
-Introduction
+Committer Environment
+
+* Introduction
This document is intended to set up the Maven committer environment.
-{Source File Encoding}
+* Source File Encoding
When editing source files, make sure you use the right file encoding. For the Maven project, UTF-8 has been chosen
as the default file encoding. UTF-8 is an encoding scheme for the Unicode character set and as such allows to encode
@@ -38,37 +40,11 @@ Introduction
exceptions to this general rule, e.g. properties files are usually encoded using ISO-8859-1 as per the JRE API, so
please keep this in mind, too.
-Subversion Configuration
-
- Before committing files in subversion repository, you need to read the
- {{{https://www.apache.org/dev/version-control.html#https-svn}Committer Subversion Access}}
- document and you must set your svn client with this properties file: {{{./svn-eol-style.txt}svn-eol-style.txt}}
-
-{Maven Code Style}
-
- The following sections show how to set up the code style for Maven in IDEA and Eclipse.
- It is strongly preferred that patches use this style before they are supplied.
-
-* IntelliJ IDEA
-
- Download <<<{{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-idea-codestyle.xml;hb=HEAD}maven-idea-codestyle.xml}}>>>
- and import it into IDEA using Intellij IDEA > Preferences > Editor > Code Style > Java > Gear icon >
- Import Scheme (> Intellij IDEA code style XML)
-
-* Eclipse
-
- Download <<<{{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-eclipse-codestyle.xml;hb=HEAD}maven-eclipse-codestyle.xml}}>>>.
-
- After this, select Window \> Preferences, and open up the configuration for Java \> Code
- Style \> Code Formatter. Click on the button labeled Import... and select the file you
- downloaded. Give the style a name, and click OK.
+* Maven Code Style
- To ensure a package import order consistent with the layout described below, download
- <<<{{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-eclipse-importorder.txt;hb=HEAD}maven-eclipse-importorder.txt}}>>>, select Window \> Preferences and
- navigate to Java \> Code Style \> Organize Imports. Click on Import... and select the downloaded
- file to change the import order.
+ Refer to {{{./conventions/code.html}Maven Code Style And Code Conventions}}
-Useful software
+* Useful software
The Maven Team uses several software. Here is a partial list:
diff --git a/content/apt/developers/conventions/code.apt b/content/apt/developers/conventions/code.apt
index 160a8c0c..51560dfe 100644
--- a/content/apt/developers/conventions/code.apt
+++ b/content/apt/developers/conventions/code.apt
@@ -28,8 +28,12 @@
Maven Code Style And Code Conventions
- This document describes how developers and contributors should format code
+ This document describes the rules for how the sources should be formatted
in order to improve consistency, readability and maintainability.
+ As the formatting is automatically enforced or even applied with {{{https://github.com/diffplug/spotless/tree/main/plugin-maven}spotless-maven-plugin}} for all projects
+ using {{{/pom/maven/index.html}Maven Project Parent POM 38 or newer}} developers usually don't need to care and the following sections are just for informational purposes.
+
+%{toc|section=1|fromDepth=2|toDepth=3}
* Generic Code Style And Convention
@@ -38,11 +42,8 @@ Maven Code Style And Code Conventions
* <<License Header>>: Always add the current {{{https://www.apache.org/legal/src-headers.html#headers}ASF license header}}
in all files checked into the source code repository.
- * <<Trailing Whitespace>>: Remove all trailing whitespace. If you use
- Eclipse, you can use the
- {{{http://andrei.gmxhome.de/anyedit/}Anyedit Eclipse Plugin}}.
-
-~~ * Using SVN properties like \$Id: \$ => Is it a wanted goal for all files like java or apt?
+ * <<Trailing Whitespace>>: No trailing whitespaces allowed.
+
[]
and the following style:
@@ -59,108 +60,8 @@ Maven Code Style And Code Conventions
** {Java Code Style}
- The Maven style for Java is mainly:
-
- * <<White space>>: One space after control statements and between arguments (e.g. <<<if ( foo )>>> instead of
- <<<if(foo)>>>), <<<myFunc( foo, bar, baz )>>> instead of <<<myFunc(foo,bar,baz)>>>).
- No spaces after methods names (i.e. <<<void myMethod(), myMethod( "foo" )>>>)
-
- * <<Indentation>>: Always use 4 space indents and <<never>> use tabs!
-
- * <<Blocks>>: Always enclose with a new line brace.
-
- * <<Line wrapping>>: Always use a 120-column line width for Java code and Javadoc.
-
- * <<Readingness>>: Specify code grouping members, if needed. For instance in a Mojo class, you could have:
-
-+-----+
-public class MyMojo
-{
- // ----------------------------------------------------------------------
- // Mojo components
- // ----------------------------------------------------------------------
-
- /**
- * Artifact factory.
- *
- * @component
- */
- private ArtifactFactory artifactFactory;
-
- ...
-
- // ----------------------------------------------------------------------
- // Mojo parameters
- // ----------------------------------------------------------------------
-
- /**
- * The POM.
- *
- * @parameter expression="${project}"
- * @required
- */
- private MavenProject project;
-
- ...
-
- // ----------------------------------------------------------------------
- // Mojo options
- // ----------------------------------------------------------------------
- ...
-
- // ----------------------------------------------------------------------
- // Public methods
- // ----------------------------------------------------------------------
-
- /**
- * {@inheritDoc}
- */
- public void execute()
- throws MojoExecutionException
- {
- ...
- }
-
- // ----------------------------------------------------------------------
- // Protected methods
- // ----------------------------------------------------------------------
- ...
-
- // ----------------------------------------------------------------------
- // Private methods
- // ----------------------------------------------------------------------
- ...
-
- // ----------------------------------------------------------------------
- // Static methods
- // ----------------------------------------------------------------------
- ...
-}
-+-----+
-
- []
-
- The following sections show how to set up the code style for Maven in IDEA and Eclipse.
- It is strongly preferred that patches use this style before they are applied.
+ Maven adopts the {{{https://github.com/palantir/palantir-java-format}palantir Java format}}.
-*** IntelliJ IDEA
-
- Download <<<{{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-idea-codestyle.xml;hb=HEAD}maven-idea-codestyle.xml}}>>>
- and import it into IDEA using Intellij IDEA > Preferences > Editor > Code Style > Java > Gear icon >
- Import Scheme (> Intellij IDEA code style XML)
-
-*** Eclipse
-
- Download <<<{{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-eclipse-codestyle.xml;hb=HEAD}maven-eclipse-codestyle.xml}}>>>.
-
- After this, select Window \> Preferences, and open up the configuration for Java \> Code
- Style \> Code Formatter. Click on the button labeled Import... and select the file you
- downloaded. Give the style a name, and click OK.
-
- To ensure a package import order consistent with the layout described below, download
- <<<{{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-eclipse-importorder.txt;hb=HEAD}maven-eclipse-importorder.txt}}>>>, select Window \> Preferences and
- navigate to Java \> Code Style \> Organize Imports. Click on Import... and select the downloaded
- file to change the import order.
** {Java Code Convention}
@@ -190,21 +91,20 @@ public class MyMojo
* import <<javax.*>>
- * blank line
-
* import <<java.*>>
* blank line
* import <<all other imports>>
- * blank line
-
- * import <<static all other imports>>
-
[]
all imports in each group should be sorted alphabetically.
+
+ To ensure a package import order consistent with the layout described above, download
+ <<<{{{https://gitbox.apache.org/repos/asf?p=maven-shared-resources.git;a=blob_plain;f=src/main/resources/config/maven-eclipse-importorder.txt;hb=HEAD}maven-eclipse-importorder.txt}}>>>, select <Window \> Preferences> and
+ navigate to <Java \> Code Style \> Organize Imports>. Click on <Import...> and select the downloaded
+ file to change the import order.
** {JavaDoc Convention}
@@ -320,9 +220,6 @@ public class MyMojo
[]
- <<Note>>: There exist two alternatives to change order of a pom file
- {{{https://www.mojohaus.org/tidy-maven-plugin/}Tidy Maven Plugin}} or the
- {{{https://github.com/Ekryd/sortpom}Sortpom Maven Plugin}}.
** {XDOC Code Convention}