Coding Guidelines
1. General
-
The OpenEMS Coding Guidelines are based on (and complement) the Java Coding Convention.
-
Limit pull requests to a small and closed topic.
2. OpenEMS Edge & Backend
2.1. Java Code
-
Limit Pull-Request to only one bundle/directory preferred
-
Remove unnecessary console.logs
-
Remove unnecessary empty lines
-
Never use System.out.println()
-
Fix all errors & warnings
-
Use precise naming for methods/functions
-
Use narrow scopes for variables; avoid class variables
-
Split code in Interface, Implementation(..Impl) and Config files
-
Use modern Java 17 syntax (e.g. 'var' keyword, streams, etc.)
-
Add readme.adoc to a new bundle
-
Review data in bnd.bnd file
-
Format all files via Eclipse Autoformat, organize Imports, apply Checkstyle suggestions (see below)
-
Avoid unnecessary comments on self explaining code
-
Add comments to code that is difficult to understand
-
Prefer functional programming (e.g. use Lambda expressions)
-
Add JUnit tests.
-
Run ./tools/prepare-commit.sh script
2.2. Tool support
While IntelliJ also works, Eclipse IDE is the officially supported development environment. It also provides tool support for guided assistance via bndtools.
Use Eclipse [built-in]
Code Formatting Rules
-
Eclipse → Window → Preferences → Java → Code Style → Formatter → ActiveProfile → select →
Eclipse [built-in]
Before you commit files, run the Eclipse code formatter on each java source code file (Ctrl + Shift + F).
Use Eclipse checkstyle plugin Eclipse-cs
. Install it with
-
Eclipse → Help → Eclipse Marketplace → Find →
Eclipse-cs
→ Install
Configure it with
-
Eclipse → Window → Preferences → New →
-
Type:
Project Relative Configuration
-
Name:
OpenEMS
-
Location:
/cnf/checkstyle.xml
-
Later set OpenEMS
as default. Enable Checkstyle for every bundle you like in the Bndtools Explorer in the bundles context menu.
4. Git-Flow workflow
-
OpenEMS development follows the Git-Flow workflow.
-
Choose precise naming of pull request and its comments when making a pull request
-
After opening the Pull-Request, review for yourself the actual changes line by line in the 'files' tab on Github. Ask for review only after you checked the actual changes again this way.
-
Ask for review when pull request is ready for review (not before)
Note: If you realize, that you added files accidentally, you can always reset them to the current 'develop' state with the command git checkout develop <filename>