# APX Style Guide

The purpose of this document is to define the organizational and naming conventions for the code that runs Advanced Pins.

The plugin is split into two types of code: Server-side PHP that runs in a WordPress environment on servers, and client-side JavaScript that also runs in a WordPress environment on any and every browser.

Rather than viewing the two languages as different utilities, we'll see them as different bodies of the same entity and will try to format the code across both languages as consistently as possible. Due to some languge constructs there will be some difference specfic to each, but the guidelines below generally apply to all code (JavaScript or PHP) found in APX files.

# Namespace

Except for the main plugin file, all PHP files are namespaced to `apx`.

# General styles

The preference is to have as much code visible on the screen at any given point in time. Ways to acheive this include intentional use of indentation and limited use of indentation.

In this reference and in code comments, we refer to variable names in backticks, such as `settings`. 

Function names should be concise and descriptive, and should the in direct relation to the name of the file they are in. For example, files in `admin.php` has functions like `handle_admin`, `admin_head`, and `save_meta_fields`. 


# Comments 

Every function should have a one-line comment describing the body or side effects of the function. 
In the TypeScript files, functions should be well typed and avoid use of overly generic types, namely `any`. description. 

# File annotations

Each file is a collection of related functionality. The top of every file should have a banner comment explaining the scope of the file. Try to limit the length of comment to two paragraphs of four sententences each.



# Spaces and Indentation

Indentation is 2 space characters in width. 
Aim to keep every line at or under 80 characters. Reasonable exceptions are long strings of display text, such as a settings 

 # # Function Declarations

The opening arrow or bracket of a function always goes on the same line as the function name. The body always goes on the next line indented by two spaces. 

 # # Variables
 
For scalar types (number, string, boolean), the variable name and the value should go on the same line. 
For arrays and objects, the name should be on its own line and the contents each on its own newline.

```

$use_tags = true;
$pinterest_username = 'SuzyQueenBee';

// PHP
$new_array = 
  [ 'first item'
  , 'second item', 
  , 'thirdly',
  , 'fourinal' ];

// JavaScript

const tags = 
  [ 'cake'
  , 'chocolate'
  , 'recipe' ]
  
 let tag = tags[0]
 
const props = 
  [ 'title'
  , 'name'
  , 'id'
  , 'color' ]

const model = 
  { id: 0
  , parentNode: document.querySelector('body')
  , response: null }
  ```

# Function Return Values

Every function must include a minimum of one explicit `return` statement, except when using implicit return arrow functions. 

```
function multiply(x, y) { 
  return x * y
}
```
For arrow functions, the returned value must be the only item on the next newline. One-liner functions are not permitted as they reduce the clarity of the code.

```
// Inconsenstent body length  means functions end up on two or three lines.
const multiplyAndTransform = (x, y, callback) => callback(callback(callback(callback(x * y)))))
  
// Consenstent body length  means functions are always on two lines. 
const multiplyAndTransform = (x, y, callback) => 
  callback(callback(callback(callback(x * y)))))

```


# PHP 
Advanced Pins preferes functions over classes, and maintains the bear minimum number of classes required to integrate with WordPress. Our own utilities do not use PHP classes or objects, and instead favor organizing data in arrays and callbacks. This makes using APX methods as easy as calling them from our namespace as long as the plugin is active. 

# JavaScript

To reduce clutter on the screen, we utilise JavaScript's Automatic Semicolon Insertion. Do not use semicolons to end statements or expressions.