JumpGate Code Style Guide


Introduction

The goal of this guide is to create a unified set of code style rules that all JumpGate packages follow. If you want to use these for your app as well feel free. If you have different guidelines modify this document to suit your needs.

PSR-1 and PSR-12

To begin with, we MUST follow PHP's PSR-1 and PSR-12. These two PHP-FIG standards are always in effect and followed. At times we may add extra details to something that is avoided by these, but if it's mentioned in them, we will follow. You can add PSR-2 code sniffing to your IDE to make sure you are always consistent.

Additions to PSR

Now, we will specify some things that we consider important that are not covered by PSR standards.

Naming Convention

These are areas in the code where we feel there should be accepted conventions and conformity.

  1. Route prefixes SHOULD ALWAYS be singular.
    1. This solves the confusion of some being plural and some being singular. By using singular you avoid the problem of some being just an s and some being ies.
  2. Route names SHOULD BE singular.
    1. For example, if your service is called Announcing your route names should all begin with announcement.
  3. Route names SHOULD ALWAYS begin with their prefix when it's not default.
    1. For example, if your in the admin context your route name should begin with admin.
  4. Classes performing a specific function MUST NOT contain the function word in their name.
    1. Examples:
      1. Files in the app/Http/Controllers directory MUST NOT have the word Controller in their name.
      2. Interface files MUST NOT contain the word Interface in their name.
    2. The folder or class type does a perfect job of explaining what the object is.

Controllers

Here are a few specific rules for controllers.

  1. When the controller is in the base (app/Http/Controllers) directory, it MAY contain the word controller.
  2. Controller names MUST be singular.
  3. You SHOULD TRY to only the standard 7 resourceful actions on a controller.
    1. If you can;t fit what you need to do in the following actions, you may need a new controller.
      1. Index
      2. Show
      3. Create
      4. Store
      5. Edit
      6. Update
      7. Destroy
    2. This is a great video on this subject.

Services

For consistency the following rules should be observed.

  1. You MUST name your service as a verb when possible.
    1. Incentivizing instead of Incentives.
  2. You SHOULD NOT add the type of class to the name.
    1. The Incentive controller should be called Incentive and not IncentiveController.
  3. You MUST use singular names for your controllers.
    1. Incentive and not Incentives.
  4. You MUST keep resource route names singular.
    1. This is for consistency and to avoid confusion in spelling.