JKFramework Naming and Coding Convention

This document contains the Naming and Coding Convention (NCC) that is recommended be used in the development of JK-Framework based systems.

The coding conventions shall include the convention for:

  1. Project names and artifacts.

  2. Source code.

  3. Rest API.

  4. Database components.

  5. Front-End

  6. Web Pages.

  7. File-names

  8. Shell scripts

Project Name and Artifacts

Project names and artifacts shall be: . All small-with dashes . Prefix with {system-name}-{component-layer}-

Examples:

  1. appstudio-frontend-accounts

  2. codegen-backend-admin

  3. appgen-microservice-customers

Source Code

Since Java will be used as the primary programming language JK-Framework based projects, the Java coding and naming convention shall be used. Full documentation of the Java coding convention can be found at: https://www.oracle.com/java/technologies/javase/codeconventions-contents.html

Main points to consider when writing Java code:

  1. Package:

    1. name is all small without underscore or dashes.

    2. For any class, the package should be : com.{company-name}.{system-name}.{component-layer}.{package-name}

  2. Class:

    1. Class name should be noun

    2. Should be camel case with first letter is capital

    3. No underscores should be included

  3. Variables:

    1. Should be noun.

    2. Camel case with small for the first letter.

    3. No underscores should be included

  4. Methods:

    1. Should be verb

    2. Camel case with small for the first letter

    3. No underscores or dashes

  5. Constants:

    1. All the constants should be declared in com.{company-name}.{system-name}.{component-layer}.{packagename}.Constants class.

    2. All should be all capital with underscores.

    3. Common constants should be declared in com.{company-name}.{system-name}.commons.Constants class in the {system-name}-commons project.

Rest API’s and Microservices

All the microservices should be declared and named as follows:

  1. Should be put in a project with the name {system-name}-microservices-{service-name}

  2. The package should be com.{company-name}.{system-name}.services.{servicename}

  3. The Rest service class should be in controllers package, where the full package name should be com.{company-name}.{system-name}.services.{servicename}.controllers

  4. The rest service should be called {ServiceName}Controller

  5. The service should follow the Mature Rest Services convention where HTTP methods will be the logical indication for the methods actual functionality. Check out the Richardson maturity model at https://restfulapi.net/richardson-maturity-model/#:~:text=This%20model%20of%20division%20of,mature%20it%20shall%20be%20considered.

Database components

Oracle

For Oracle databases, the NCC should be declared as follows:

  1. All database objects names should be capital with underscores.

  2. Table names:

    1. Should be plural

    2. Prefixed with the module name.

    3. Should always have an AUTO_INCREMENT primary key named ID

    4. Examples: (CODEGEN_CUSTOMERS, SEC_AUDITS, OPS_MONITOR)

  3. Table fields: Should be singular (CUSTOMER_NUMBER)

  4. Views: Should be prefixed with VI_{MODULE_NAME}

  5. Sequences: Should be prefixed with SEQ_{MODULE_NAME}

Front-end

Projects shall follow the Single Page design approach as possible, where each page will be deployed as individual application.

So, in each application all web front-end applications should be named:

  1. Small with dashes

  2. The project name should be {system-name}-frontend-{app-name}

  3. The project should be Maven war project

  4. The package name should be com.{company-name}.{system-name}.web

  5. The controllers (JSF managed beans) shall be located in com.{company-name}.{system-name}.web.controllers

  6. All the JSF controllers bean should be named {ClassName}Controller.

  7. The core business page shall be named index.xhtml and shall be located at the root of the web folder src/main/web

  8. The default template should be located at src/main/web/WEB-INF/templates/default.xhtml

  9. The error template should be located at src/main/web/WEB-INF/templates/error.xhtml

  10. There should be a custom error pages located src/main/web/errors