Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/netherphp/standards
A project documenting the code standards used by the Nether projects.
https://github.com/netherphp/standards
Last synced: 12 days ago
JSON representation
A project documenting the code standards used by the Nether projects.
- Host: GitHub
- URL: https://github.com/netherphp/standards
- Owner: netherphp
- Created: 2015-08-12T20:41:17.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-04-13T20:47:28.000Z (9 months ago)
- Last Synced: 2024-04-14T10:58:52.890Z (9 months ago)
- Language: PHP
- Size: 160 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Nether [ˈne-thər]
[](https://github.com/netherphp/standards/actions?query=workflow%3A%22PHPCS+Test%22)
> *Located toward the bottom or more distant part of something.*
> -- Merriam-Webster Dictionary
# Nether Standards Project
Known as Nether Notation, NN, N2, or N2
This is a project to document the code conventions used by the Nether Project. As of the writing of this project there is a 99% chance you have never seen code formatted like this before - and that is O.K. - not everything needs to be cut with the same rules we used in 1972. These rules will typically depend on the flexiblity of PHP, but some of the general formatting may be portable to other languges depending on their parsers.
A lot of the rules here are based on the concept of being explicit. The developer will always explictly state their intentions, never allowing for default behaviours. This is for a few reasons. First being it shows that the developer has actually thought about what their code is doing. Second, it helps lessen backwards compatbility issues in the future when a default behaviour changes. And yes, it does happen. Finally, the entire format and rules are based on the concept that the code can be as self documenting as possible to minimise the amount of metadata needed to describe various entities.
## Automated Formatting
This repository contains a `phpcs` standard for testing and automated reformatting of source to fit the standard. For instructions on installation and automated testing against this standard please refer to the Wiki page:
https://github.com/netherphp/standards/wiki/Nether-Notation-Coding-Standard-for-PHP_CodeSniffer
## General Standards
* PascalCaseAllTheThings except:
- UPPERCASE for boolean constants (TRUE, FALSE) and NULL.
- lowercase for core types (int, float, etc...)
* Tabs for indenting.
* \n for new lines.
* initialize variables in scopes prior to use.
* explicit "return" at end of functions.
* design for strict types in mind.
* attempt to keep lines shorter than 80 characters.
* prefer single quotes when not using string evaluation.
* anything that can have a type, should have a type.
* no derp commas (trailing commas at the end of arrays, etc).
## Inline Documentation.
All symbol documentation is done with Nether Senpai format documentation. Unlike typical docblocks, these come after the symbol they define on the same indention level. Senpai blocks are opened with /\*// and closed with //\*/ - more on the documentation when I finish writing this document and start writing that one.
Nether Senpai generates as much documentation from the code itself before noticing the comment that describes it. This reduces the amount of junk you need to manually write in the documentation. Taking advantage of featured added in PHP 7.0+ 7.1 most code can be completely self document itself.
NN will use Senpai notation until the day PHP has real annotation support that is not via the slow Reflection system you do not want to use within a production project.
This means a typical method will look like this:
```php
Next())
$List[] = $Row;
```
**A WHILE with braces.**
```php
Next()) {
$Row->Cached = FALSE;
$List[] = $Row;
}
```
## Argument Lists and Array Definitions
If a call to a function or method requires multiple arguments, and that list may get lengthy or hard to read, arguments will be defined on new lines on the next level of indention.
```php
1,
'Else' => 2,
'MoreData' => 3
];
```
If items in the array are being grouped during their definition it is acceptable to have multiple levels of padding unique to each group.
```php
1,
'Else' => 2,
'MoreData' => 3,
// mostly optional for whatever.
'Four' => 4,
'Five' => 5,
'Six' => 6
];
```
## Strings
If a string DOES NOT require data evaluation then single quotes will be used. If a string DOES require data evaluation then double quotes may be used, if the resulting string will not cause the line length to get unwieldy. The preferred method for building or concatinating long strings is via the `sprintf` function.
```php
GetName()
);
```
Literal concationation with the dot operator is not considered acceptable in any situation.
```php
NULL,
'Page' => 1,
'Limit' => 25,
'Owner' => NULL
]);
// ...
return $Result;
}
}
```
## Method Reduction of Concerns
The this naming convention would not be used if the split methods are to be reusable by many different processes. This section is mainly for separation of concerns where the separated actions are useless on their own.
To split a long method into smaller units of code, reduced concern methods shall be prefixed with the method name they are designed to work with, with the descriptive action being separated by a netherscore in the method name.
```php
GetFileContents_ReadFile($Filename);
$Obj = $this->GetFileContents_ParseData($Data);
}
catch(Exception $Error) {
// log error or something.
return NULL;
}
return $Obj;
}
protected function
GetFileContents_ReadFile(string $Filename):
string {
/*//
check that the file is readable from the filesystem.
//*/
if(!file_exists($Filename) || !is_readable($Filename)
throw new Exception("{$Filename} not found or unreadable.");
return file_get_contents($Filename);
}
protected function
GetFileContents_ParseData(string $Data):
StdClass {
/*//
check that the file was parsable.
//*/
$Obj = json_decode($Data);
if(!is_object($Data))
throw new Exception("Unable to parse data.");
return $Obj;
}
}
```
## Method Chaining
When using chained methods and the line may potentially become unwieldy, then each link in the chain will be placed on a new line at the same indention level as the symbol the chain originates from. Calls like this will be isolated by empty lines above and below them.
```php
NewVerse())
->Select('Table')
->Fields(['One','Two','Three'])
->Where(['Five=:InputFive','Six=:InputSix'])
->Limit(25);
$Result = $DB->Query($Query,$Input);
```
It is preferred that you convey context awareness when chaining. In the above example all chained methods return the original object. Chaining should stop when the object returned is not the same object. The parens that wrap the first line of that query chain convey understanding by the authour of the context of this chain. This is the object, the following chain follows.
## Variable Scope Initialization.
While not required by PHP variables will be declared prior to later use at the beginning of their parent scopes - meaning all variables are to be be declared at the top of functions and methods and not invented in the middle of logic. If their value cannot be detemrined at declaration time, then they should be initialized as NULL until then.
This includes, and even specifically is targeting, any variables that would normally be invented on the fly in `for` or `foreach` loops, `catch`, etc.
```php
TotallyAnArrayProperty as $Child) {
if($Child->TotallyAnBoolProperty === TRUE)
$Output++;
}
return $Output;
}
}
```
## HTML Templating
When working within the scope of an HTML template file, code structures will be written using their Alternative Syntax. Short tag echo will not be used.
```php
```
# Changelogue
## 2021-04-09
* It has been decided to reverse a decision about the casing of built in core types (int, float, etc) such that they should not be PascalCased anymore. All other PascalCase rules still apply elsewhere.
```php
public function AddTwo(Int $Input): Int;
public function AddTwo(int $Input): int;
```
## 2020-12-04
* It has been decided the rule surrounding namespace/class `use` calls should no longer be followed. It is now preferred that `use` calls are only single line and without any leading slashing.
```php
use
\Nether as Nether,
\Local as Local;
use Nether;
use Local;
```
## 2020-05-13
* Add rule that denies derp commas in arrays and function argument lists