diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/howto-codestyle')
20 files changed, 571 insertions, 0 deletions
diff --git a/src/site-docs/adoc/fragments/howto-codestyle/01-introduction.adoc b/src/site-docs/adoc/fragments/howto-codestyle/01-introduction.adoc new file mode 100644 index 000000000..776ad3448 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/01-introduction.adoc @@ -0,0 +1,27 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Introduction: APEX Codestyle + +This page describes how to apply a code style to the APEX Java projects. +The provided code templates are guidelines and are provided for references and as examples. +We will not engage in "holy war" on style for coding. +As long as the style of a particular block of code is understandable, consistent, and readable, please feel free to adapt or modify these guides or use other guides as you see fit. + +The JAutoDoc and Checkstyle Eclipse Plugins and tools are useful and remove a lot of the tedium from code documentation. +Use them to check your code and please fix any issues they identify with your code. + +The templates and examples on this page have been tested on a clean installation of Eclipse Oxygen Release (4.7.0) on Ubuntu Linux 16.04 LTS. + +The Apex settings referred to on this page are also available in the apex-model GIT repository in the APEX model repository in apex-model/apex-model.build-tools/src/main/resources/`. + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/02-rules.adoc b/src/site-docs/adoc/fragments/howto-codestyle/02-rules.adoc new file mode 100644 index 000000000..8b7f122b8 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/02-rules.adoc @@ -0,0 +1,38 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Java coding Rules + +* APEX is (in large parts) a platform (or middleware), so link:https://en.wikipedia.org/wiki/Software_design_pattern[Software Design Patterns] are a good thing +* The link:https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)[Solid Principles] apply +* Avoid class fields scoped as `protected` + ** They break a lot of good design rules, e.g. most SOLID rules + ** For a discussion see this link:https://softwareengineering.stackexchange.com/questions/162643/why-is-clean-code-suggesting-avoiding-protected-variables[Stackoverflow Question] +* If you absolutely need `protected` class fields they should be `final` +* Avoid `default` scope for class fields and methods + ** For fields: use `public` or `private` (see also above) + ** For methods: use `public` for general use, `protected` for specialization using inheritance (ideally `final`), `private` for everything else +* Method parameters that are not changed in the method should be marked `final` +* Every package must have a `package-info.java` file with an appropriate description, minimum a descriptive one liner +* Every class must have + ** The common header (copyright, file, date) + ** Javadoc header for the class with description of the class and author + ** Javadoc for _all public__ fields + ** If possible, Javadoc for __private__ fields, at least some documentation for private fields + ** Javadoc for __all__ methods +* All project must build with all tests on Unix, Windows, __and__ Cygwin + ** Support all line endings in files, e.g. `\n` and `\r\n` + ** Be aware of potential differences in exception messages, if testing against a message + ** Support all types of paths: Unix with `/`, Windows with an optinal drive `C:\` and `\`, Cygwin with mixed paths + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/10-plugin-jautodoc.adoc b/src/site-docs/adoc/fragments/howto-codestyle/10-plugin-jautodoc.adoc new file mode 100644 index 000000000..c0b6fa31f --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/10-plugin-jautodoc.adoc @@ -0,0 +1,25 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Eclipse Plugin: JAutodoc + +This plugin is a helper plugin for writing Javadoc. +It will automatically create standard headers on files, create package-info.java files and will put in remarkably good stub Javadoc comments in your code, using class names and method names as hints. + +Available from the Eclipse Marketplace. +In Eclipse Help->Eclipse Marketplace... and type `JAutodoc`. +Select JAutodoc when the search returns and install it. + +You must configure JAutoDoc in order to get the most out of it. +Ideally JAutoDoc should be configured with templates that cooperate with the inbuilt Eclipse Code Formatter for best results. + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/11-plugin-checkstyle.adoc b/src/site-docs/adoc/fragments/howto-codestyle/11-plugin-checkstyle.adoc new file mode 100644 index 000000000..a6a93bfa4 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/11-plugin-checkstyle.adoc @@ -0,0 +1,26 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Eclipse Plugin: Checkstyle + +This plugin integrates link:http://checkstyle.sourceforge.net/[Checkstyle] into Eclipse. +It will check your code and flag any checkstyle issues as warnings in the code. + +Available from the Eclipse Marketplace. +In Eclipse Help->Eclipse Marketplace... and type "Checkstyle". +Select "Checkstyle Plug-in" when the search returns and install it. +Note that "Checkstyle Plug-in" may not be the first result in the list of items returned. + +You must configure Checkstyle in order to get the most out of it. +There are two built-in style templates in Checkstyle (from Oracle and Google) but user will almost certainly wish to tweak these. + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/20-configure-eclipse-templates.adoc b/src/site-docs/adoc/fragments/howto-codestyle/20-configure-eclipse-templates.adoc new file mode 100644 index 000000000..9f13e817a --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/20-configure-eclipse-templates.adoc @@ -0,0 +1,28 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Configure Eclipse + +* Set the template for Eclipse code clean up + . menu:Eclipse[Window > Preferences > Java > Code Style > Clean Up] -> kbd:[Import...] + . Select your template file (`ApexCleanUpTemplate.xml`) and apply it +* Set the Eclipse code templates + . menu:Eclipse[Window > Preferences > Java > Code Style > Code Templates] -> kbd:[Import...] + . Select your templates file (`ApexCodeTemplates.xml`) and apply it + ** Make sure to set your email address in generated comments by selecting "Comments->Types" in the "Configure generated code and comments:" pane, then change the email address on the @author tag to be your email address +* Set the Eclipse Formatter profile + . menu:Eclipse[Window > Preferences > Java > Code Style > Formatter] -> kbd:[Import...] + . Select your formatter profile file (`ApexFormatterProfile.xml`) and apply it + +The templates mentioned above can be found in `apex-model/apex-model.build-tools/src/main/resources/eclipse` + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/21-configure-jautodoc-templates.adoc b/src/site-docs/adoc/fragments/howto-codestyle/21-configure-jautodoc-templates.adoc new file mode 100644 index 000000000..48c8ee6d7 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/21-configure-jautodoc-templates.adoc @@ -0,0 +1,25 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Configure JAutodoc (Eclipse) + +Import the settings for JAutodoc: + + . menu:Eclipse[Window > Preferences > Java > JAutodoc] -> kbd:[Import All...] (at bottom of the JAutodoc preferences window) + . Leave all the preferences ticked to import all preferences, browse to the JAutodoc setting file (`ApexJautodocSettings.xml`) and press kbd:[OK] + . Set your email address in the package Javadoc template + * Press kbd:[Edit Template...] in the Package Javadoc area of the JAutodoc preferences window, and change the email address on the `@author` tag to be your email address + . Now, apply the JAutodoc settings + +The templates mentioned above can be found in `apex-model/apex-model.build-tools/src/main/resources/eclipse` + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/30-configure-checkstyle-maven.adoc b/src/site-docs/adoc/fragments/howto-codestyle/30-configure-checkstyle-maven.adoc new file mode 100644 index 000000000..2e6698fff --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/30-configure-checkstyle-maven.adoc @@ -0,0 +1,45 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Configure Checkstyle (Maven) + +When using a custom style configuration with Checkstyle, the definition of that style must of course be available to Checkstyle. +In order not to have to distribute style files for checkstyle into all Maven modules, it is recommended that a special Maven module be built that contains the checkstyle style definition. +That module is then used as a dependency in the __POM__ for all other modules that wish to use that checkstyle style. +For a full explanation see link:https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html[the explanation of Checkstyle multi-module configuration]. + +In Apex, the module `apex-model.build-tools` provides the Apex checkstyle style files as resources in `src/main/resources/checkstyle`. +This style is a slightly tweaked version of the standard Google checkstyle style that allows longer lines and has some other checks slightly relaxed. +Therefore, all modules that wish to use the Apex style must put the following build directive into their `pom.xml`. + +[source%nowrap,xml] +---- +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-checkstyle-plugin</artifactId> + <version>2.17</version> + <dependencies> + <dependency> + <groupId>org.onap.policy.apex.model</groupId> + <artifactId>apex-model.build-tools</artifactId> + <version>${project.version}</version> + </dependency> + </dependencies> + <configuration> + <configLocation>checkstyle/apex_style_checks.xml</configLocation> + <headerLocation>checkstyle/apex_header.txt</headerLocation> + </configuration> +</plugin> +---- + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/31-run-checkstyle-maven.adoc b/src/site-docs/adoc/fragments/howto-codestyle/31-run-checkstyle-maven.adoc new file mode 100644 index 000000000..381153f7b --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/31-run-checkstyle-maven.adoc @@ -0,0 +1,30 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Run Checkstyle (Maven) + +Run Checkstyle using Maven on the command line with the command: + +[source%nowrap,sh] +---- +mvn checkstyle:check +---- + +On the main APEX project, run a full checkstyle check as: + +[source%nowrap,sh] +---- +mvn checkstyle:checkstyle -DapexAll +---- + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/32-configure-checkstyle-eclipse.adoc b/src/site-docs/adoc/fragments/howto-codestyle/32-configure-checkstyle-eclipse.adoc new file mode 100644 index 000000000..507cbb9bd --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/32-configure-checkstyle-eclipse.adoc @@ -0,0 +1,36 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Configure Checkstyle (Eclipse, globally) + +. Set up a module with the Checkstyle style files (see above) +. In menu:Eclipse[Window > Preferences] go to Checkstyle +. Import the settings for Checkstyle + * Press kbd:[New...] to create a new __Global Check Configurations__ entry + * Give the configuration a name such as __Apex Checkstyle Configuration__ and select the __External Configuration File__ form in the __Type__ drop down menu + * Browse to the Checckstyle setting file (`ApexCheckstyleSettings.xml`) and press kbd:[OK] +. Press kbd:[OK] + * You may now get an __Unresolved Properties found__ dialogue + * This is because there is a second Checkstyle configuration file required to check file headers +. Press kbd:[Edit Properties...] and press kbd:[Find unresolved properties] on the next dialogue window +. The plugin will find the `${checkstyle.header.file}` property is unresolved and will ask should it be added to the properties, click kbd:[yes] +. Now, select the row on the dialogue for the `checkstyle.header.file property` and click kbd:[Edit...] +. Set the value of the `checkstyle.header.file property` to `<your-apex-git-location>/apex-model/apex-model.build-tools/src/main/resources/checkstyle/apex_header.txt` + * Of course replacing the tag `<your-apex-git-location>` with the location of your Apex GIT repository +. Press kbd:[OK], kbd:[OK], kbd:[OK] to back out to the main Checkstyle properties window +. Select the __Apex Checkstyle Configuration__ as your default configuration by selecting its line in the __Global Check Configuraitons__ list and clicking kbd:[Set as Default] +. Press kbd:[Apply and Close] to finish Checkstyle global configuration + +The templates mentioned above can be found in `apex-model/apex-model.build-tools/src/main/resources/eclipse` + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/33-configure-checkstyle-blueprint.adoc b/src/site-docs/adoc/fragments/howto-codestyle/33-configure-checkstyle-blueprint.adoc new file mode 100644 index 000000000..d4cb45914 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/33-configure-checkstyle-blueprint.adoc @@ -0,0 +1,35 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Configure Checkstyle Blueprint + +As well as being configured globally, Checkstyle must be configured and activated for each project in Eclipse. +In order to make this process less tedious, set up the first project you apply Checkstye to as a blueprint project and then use this blueprint for all other projects. + +. Select the project you want to use as a blueprint + * For example, `apex-model.basic-model` in `apex` and enter the project properties by right clicking and selecting menu:Properties[] +. Click __Checkstyle__ on the properties to get the Checkstyle project configuration window +. Click the box __Checkstyle active for this project__ and in the __Exclude from checking...__ list check the boxes: + * [*] __files outside source directories__ + * [*] __derived (generated) files__ + * [*] __files from packages:__ +. Now, in order to turn off checking on resource directories and on JUnit tests + * Select the line __files from packages:__ in the __Exclude from checking...__ list and click kbd:[Change...] +. On the __Filter packages__ dialogue + * Check all the boxes except the top box, which is the box for __src/main/java__ + * Ensure that the __recursively exclude sub-packages__ check box is ticked + ** [*] __recursively exclude sub-packages__ + * Press kbd:[OK] +. Press kbd:[Apply and Close] to apply the changes + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/40-use-eclipse-source-operations.adoc b/src/site-docs/adoc/fragments/howto-codestyle/40-use-eclipse-source-operations.adoc new file mode 100644 index 000000000..6ead28a7f --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/40-use-eclipse-source-operations.adoc @@ -0,0 +1,48 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= + +== Use Eclipse Source Operations + +Eclipse Source Operations can be carried out on individual files or on all the files in a package but do not recurse into sub-packages. +They are available as a menu in Eclipse by selecting a file or package and right clicking on __Source__. +Note that running __Clean Up...__ with the Apex clean up profile will run __Format__ and __Organize Imports__. +So if you run a clean up on a file or package, you need not run __Format__ or __Organize Imports__. + +We recommend you use the following Eclipse Source Operations: + +. __Format__ applies the current format definition to the file or all files in a package +. __Organize Imports__ sorts the imports on each file in standard order +. __Clean Up__ runs a number of cleaning operations on each file. The Apex clean up template + ** Remove `this` qualifier for non static field accesses + ** Change non static accesses to static members using declaring type + ** Change indirect accesses to static members to direct accesses (accesses through subtypes) + ** Convert control statement bodies to block + ** Convert `for` loops to enhanced `for` loops + ** Add final modifier to private fields + ** Add final modifier to local variables + ** Remove unused imports + ** Remove unused private methods + ** Remove unused private constructors + ** Remove unused private types + ** Remove unused private fields + ** Remove unused local variables + ** Add missing `@Override` annotations + ** Add missing `@Override` annotations to implementations of interface methods + ** Add missing `@Deprecated` annotations + ** Add missing serial version ID (generated) + ** Remove unnecessary casts + ** Remove unnecessary `$NON-NLS$` tags + ** Organize imports + ** Format source code + ** Remove trailing white spaces on all lines + ** Correct indentation + ** Remove redundant type arguments + ** Add file header (JAutodoc) + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/41-using-jautodoc.adoc b/src/site-docs/adoc/fragments/howto-codestyle/41-using-jautodoc.adoc new file mode 100644 index 000000000..0c3ab0518 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/41-using-jautodoc.adoc @@ -0,0 +1,23 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Using JAutodoc + +Similar to Eclipse Source Operations, JAutodoc operations can be carried out on individual files or on all the files in a package but do not recurse into sub-packages. +The JAutodoc operations are available by selecting a file or package and right clicking on __JAutodoc__: + +. To add a `package-info.java` file to a package, select the package and right-click menu:Jautodoc[Add Package Javadoc] +. To add headers to files select on a file (or on the package to do all files) and right click menu:JAutodoc[Add Header] +. To add JAutodoc stubs to a files, select on a file (or on the package to do all files) and right click menu:JAutodoc[Add Javadoc] + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/42-using-checkstyle.adoc b/src/site-docs/adoc/fragments/howto-codestyle/42-using-checkstyle.adoc new file mode 100644 index 000000000..f639868ae --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/42-using-checkstyle.adoc @@ -0,0 +1,32 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Using Checkstyle + +In order to use Checkstyle, you must configure it per project and then activate it per project. +The easiest way to do this is to set up one project as a blueprint and use that blueprint for other projects (see above). +Once you have a blueprint project, you can use Checkstyle on other projects as follows + +. Set up Checkstyle on projects by selecting one or more projects + * Right clicking and selecting menu:Checkstyle[Configure project(s)] from __blueprint...__ and then selecting your blueprint project + * (for example `apex-model.basic-model`) from the list of projects and pressing kbd:[OK] +. Activate Checkstyle on projects by selecting one or more projects + * Right clicking and selecting menu:Checkstyle[Activate Checkstyle] + * Now Checkstyle warnings will appear on the selected projects if they have warnings +. You can disable Checkstyle checking on a file or a package (recursively) by selecting a file or package + * Right clicking and selecting menu:Checkstyle[Clear Checkstyle violations] +. You can enable Checkstyle checking on a file or a package (recursively) by selecting a file or package + * Right clicking and selecting menu:Checkstyle[Check Code with Checkstyle] +. On individual files, you can apply fixes that clear some Checkstyle warnings + * Select the file, right click and select menu:Apply Checkstyle fixes[] + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/50-disable-eclispe-formatting.adoc b/src/site-docs/adoc/fragments/howto-codestyle/50-disable-eclispe-formatting.adoc new file mode 100644 index 000000000..adf480fb0 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/50-disable-eclispe-formatting.adoc @@ -0,0 +1,37 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Disable Eclipse Formatting (partially) + +Sometimes, the Eclipse code formatting results in correct but untidy indentation, for example when Java Persistence annotations or long sequences of lined-up assignments are formatted. +You can disable formatting for sections of code. + +. Ensure that Off/On Tags are enabled in Eclipse + . In menu:Eclipse[Window > Preferences > Java > Code Style > Formatter] window press kbd:[Edit...] + . Click on the __Off/On Tags__ tab + . Ensure that the __Enable Off/On Tags__ checkbox is checked +. Surround the section of code that you do not want the formatter to act on with comments containing the Off/On tags + + +[source%nowrap,java,numbered] +---- +// @formatter:off +// Plugin Parameters +private DistributorParameters distributorParameters = new DistributorParameters(); +private SchemaParameters schemaParameters = new SchemaParameters(); +private LockManagerParameters lockManagerParameters = new LockManagerParameters(); +private PersistorParameters persistorParameters = new PersistorParameters(); +// @formatter:on +---- + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/51-supress-checkstyle.adoc b/src/site-docs/adoc/fragments/howto-codestyle/51-supress-checkstyle.adoc new file mode 100644 index 000000000..549df0726 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/51-supress-checkstyle.adoc @@ -0,0 +1,31 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +== Supress Checkstyle (partially) + +Sometimes Checkstyle checks identify code that does not comply with Checkstyle rules. +In limited cases Checkstyle rules can be suppressed, for example where it is impossible to design the code in a way that complies with Checkstyle or where the Checkstyle rule is impossible to apply. +Checkstyle rules are suppressed as is explained in this link:https://stackoverflow.com/questions/4023185/how-to-disable-a-particular-checkstyle-rule-for-a-particular-line-of-code[Stackoverflow post]. + +The example below illustrates how to suppress a Checkstyle rule that specifies all methods must have seven parameters or less. + +[source%nowrap,java,numbered] +---- +// CHECKSTYLE:OFF: checkstyle:ParameterNumber +public myMethod(final int par1, final int par2, final int par3, final int par4, + final int par5, final int par6, final int par7, final int par8) { +} +// CHECKSTYLE:ON: checkstyle:ParameterNumber +---- + + diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-header.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-header.adoc new file mode 100644 index 000000000..ce6367ef9 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-header.adoc @@ -0,0 +1,17 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +[source%nowrap,text,subs="attributes+"] +---- +include::{apex-main-dir}/checkstyle/apex_header.txt[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-style-checks.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-style-checks.adoc new file mode 100644 index 000000000..f67a01c0a --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-checkstyle-style-checks.adoc @@ -0,0 +1,17 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +[source%nowrap,xml,subs="attributes+"] +---- +include::{apex-main-dir}/checkstyle/apex_style_checks.xml[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-checkstyle-settings.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-checkstyle-settings.adoc new file mode 100644 index 000000000..255855b43 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-checkstyle-settings.adoc @@ -0,0 +1,17 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +[source%nowrap,xml,subs="attributes+"] +---- +include::{apex-main-dir}/eclipse/ApexCheckstyleSettings.xml[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-cleanup.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-cleanup.adoc new file mode 100644 index 000000000..638d33972 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-cleanup.adoc @@ -0,0 +1,17 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +[source%nowrap,xml,subs="attributes+"] +---- +include::{apex-main-dir}/eclipse/ApexCleanUpTemplate.xml[] +----
\ No newline at end of file diff --git a/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-formatter-profile.adoc b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-formatter-profile.adoc new file mode 100644 index 000000000..dad270110 --- /dev/null +++ b/src/site-docs/adoc/fragments/howto-codestyle/99-tpl-eclipse-formatter-profile.adoc @@ -0,0 +1,17 @@ +// +// ============LICENSE_START======================================================= +// Copyright (C) 2016-2018 Ericsson. All rights reserved. +// ================================================================================ +// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE +// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode +// +// SPDX-License-Identifier: CC-BY-4.0 +// ============LICENSE_END========================================================= +// +// @author Sven van der Meer (sven.van.der.meer@ericsson.com) +// + +[source%nowrap,xml,subs="attributes+"] +---- +include::{apex-main-dir}/eclipse/ApexFormatterProfile.xml[] +----
\ No newline at end of file |