Skip to content

Coding Guideline

Jump to bottom
Jonathan edited this page Jun 13, 2019 · 4 revisions

Backend Code Guidelines

IMPORTANT NOTE

Ensure build is successful before creating pull request and try to run the app. Attach build success message to the PR description. Example can be seen here.

Table of Contents

Module Structure

  • function-app

    Contains main Spring Boot application class.

    If a new dependency is added and requires global configuration using annotations, place the annotation in the Spring Boot application class in this module.

    Another file(s) this module contains is/are application.properties file.

    If we need to add spring boot configuration properties or custom properties of our own, add the properties here. For custom properties, note that another class must be created in module function-common, package properties for accessing the custom properties.

  • function-common

    Contains common classes to be reused in many modules, such as:

    • data interface for function-validation and function-web-model modules,
    • enumerations for function-model, function-service-impl, and function-web modules,
    • exceptions thrown from function-service-impl and function-validation modules,
    • properties files used to access properties from application.properties located in function-app module.

    For enumerations and data interface, it is important to perform unit testing as they are covered in analysis scan.

  • function-data-migration

    Used for seeding and changing the format of existing data in database. We use Mongobee in this project for data migration.

    Configuration class should work just fine, so if something's not working, it is possibly the migration (change log) that is problematic.

    To add more data or to perform migration, set it up in class FunctionChangeLog by adding another method specifying the migration specification/purpose in brief. Above the method, add annotation @ChangeSet(author=<your_name>, id=<migration_name_or_id>, order=<order_of_execution>). See @ChangeSet documentation for detail.

    Note that this module can be separated from current project should the need arise.

  • function-model

    Contains entity representations and related classes for the entities (models). Each entity is placed in separate package according to each team name.

    For other classes related to models can be placed in package util, and be separated per package for each utility again.

  • function-repository

    Contains repositories for accessing data in database, placed in separate package according to each team name.

    For each interface, put @Repository annotation on top of the class.

    For every custom method that is written, create unit test for them as well.

  • function-service-api

    Contains interfaces for service methods and classes. For naming conventions can be seen in this section.

  • function-service-impl

    Contains implementation of logic for each feature and helper classes for recurring/general codes.

    Annotate each service class with @Service annotation, and implement the class' service API (interface) from function-service-api.

    For certain codes which seems to be too general, separate to package helper. For codes that are hard to test inside the service classes, separate to package helper as well.

    For each helper class, annotate @NoArgsConstructor(access = AccessLevel.PRIVATE) and set the class final so the class could not be extended. Also, for each method, use static method.

  • function-validation

    Contains all validation-related classes, from annotations to validators. Format for each annotation or validator can be seen in existing examples.

    For annotation that has target of ElementType.TYPE, use data interface as second parameter of ConstraintValidator interface implemented by custom validator. Also, for the same subject, set field on the annotation class (example can be seen at OnlyStudentCanHaveBatchAndUniversity annotation). This is to ensure that if the validator returns invalid flag, there is a source of error that can be used in errors map returned to exception controller.

    Each validator class must be tested.

  • function-web

    Contains configurations, controllers, and mappers for each feature. Separate each classes by team's name per package.

    For codes with general purposes, put them in package helper with new class, or update existing class if necessary.

    Each class in this module, except configuration, must be tested.

  • function-web-model

    Contains web representations (web models) for web request or response. Annotations from hibernate or javax validation modules, and from function-validation module will be used in request representation classes. Specify messages for each validation. Each representation is placed in separate package according to each team name.

    For other classes related to web models can be placed in package util, and be separated per package for each utility again.

Naming Conventions

IMPORTANT NOTE: Use style from docs/Style/FUNCTION-STYLE.xml in IntellIJ IDEA for equal code style. Please do apply it as default style when coding in function-backend project.

  • Test Method

    • Each test method must be named as follows: testGiven<Condition1AndCondition2>By<MethodFunctionalityNotItsName>Return<ExpectedObjectOrException>.
    • Special Cases
      • Controller
        • Condition must be ApiCall, then extended with other conditions.
      • Mapper
        • Request
          • After By, add name ParsingTo<ClassName>Class.
        • Response
          • After By, add name MappingTo<ClassName>Class.

Clone this wiki locally