soul-code-conduct

Edit
Update time: 2021-03-05

Development Guidelines

  • Write codes with heart. Pursue clean, simplified and extremely elegant codes. Agree with concepts in <Refactoring: Improving the Design of Existing Code> and <Clean Code: A Handbook of Agile Software Craftsmanship>.
  • Be familiar with codes already had, to keep consistent with the style and use.
  • Highly reusable, no duplicated codes or configurations.
  • Delete codes out of use in time.

Contributor Covenant Submitting of Conduct

  • Make sure all the test cases are passed, Make sure ./mvnw clean install can be compiled and tested successfully.
  • Make sure the test coverage rate is not lower than the master branch.
  • Make sure to check codes with Checkstyle. codes that violate check rules should have special reasons. Find checkstyle template from https://github.com/dromara/soul/blob/master/script/soul_checkstyle.xml, please use checkstyle 8.8 to run the rules.
  • Careful consideration for each pull request; Small and frequent pull request with complete unit function is welcomed.
  • Conform to Contributor Covenant Code of Conduct below.

Contributor Covenant Code of Conduct

  • Use linux line separators.
  • Keep indents (including blank lines) consistent with the previous one.
  • Keep one blank line after class definition.
  • No meaningless blank lines. Please extract private methods to instead of blank lines if too long method body or different logic code fragments.
  • Use meaningful class, method and variable names, avoid to use abbreviate.
  • Return values are named with result; Variables in the loop structure are named with each; Replace each with entry in map.
  • Name property files with Spinal Case(a variant of Snake Case which uses hyphens - to separate words).
  • Split codes that need to add notes with it into small methods, which are explained with method names.
  • Have constants on the left and variable on the right in = and equals conditional expressions; Have variable on the left and constants on the right in greater than and less than conditional expressions.
  • Beside using same names as input parameters and global fields in assign statement, avoid using this modifier.
  • Design class as final class except abstract class for extend.
  • Make nested loop structures a new method.
  • Order of members definition and parameters should be consistent during classes and methods.
  • Use guard clauses in priority.
  • Minimize the access permission for classes and methods.
  • Private method should be just next to the method in which it is used; writing private methods should be in the same as the appearance order of private methods.
  • No null parameters or return values.
  • Replace if else return and assign statement with ternary operator in priority.
  • Use LinkedList in priority. Use ArrayList for use index to get element only.
  • Use capacity based Collection such as ArrayList, HashMap must indicate initial capacity to avoid recalculate capacity.
  • Use English in all the logs and javadoc.
  • Include Javadoc, todo and fixme only in the comments.
  • Only public classes and methods need javadoc, other methods, classes and override methods do not need javadoc.

Contributor Covenant Unit Test of Conduct

  • Test codes and production codes should follow the same kind of code of conduct.
  • Unit test should follow AIR (Automatic, Independent, Repeatable) principle.
    • Automatic: Unit test should run automatically, not interactively. Check test result manually and System.out, log are prohibited, use assert to check test results.
    • Independent: Call each other and sequence dependency during unit test cases are prohibited. Every test case should run independent.
    • Repeatable: Unit test case should not dependency external environment, they can run repeatable.
  • Unit test should follow BCDE (Border, Correct, Design, Error) design principle.
    • Border: Border value test, test for loop border, special value and value sequence to get expect result.
    • Correct: Correct value test, test for correct value to get expect result.
    • Design: Design with production codes.
    • Error: Error value test, test for error input, exception to get expect result.
  • Without particular reasons, test cases should be fully covered.
  • Every test case need precised assertion.
  • Environment preparation codes should be separate from test codes.
  • Only those that relate to junit Assert, hamcrest CoreMatchers and Mockito can use static import.
  • For single parameter asserts, assertTrue, assertFalse, assertNull and assertNotNull should be used.
  • For multiple parameter asserts, assertThat should be used.
  • For accurate asserts, try not to use not, containsString to make assertions.
  • Actual values of test cases should be named actualXXX, expected values expectedXXX.
  • Class for test case and @Test annotation do not need javadoc.