viharm

This document describes best practices for creating software.

It is well known that some programming languages have specific requirements both presentational and functional; while others have a relaxed approach toward presentation.

The recommendations made here endeavour to create a set of best practices to suit as many languages as possible to maintain consistency in structure, semantics and layout.

Concepts to do

Fundamental concepts

Library to do

Library of assets, further categorised into types.

UI elements
Operational elements

Reusable code

Discretisation to do

Design of various applications vastly differs from each other in the way they are developed, and there can be no common standard to control the architecture of applications.

The general guideline is towards discretisation of an applicaiton into smaller logical units of code which work together to provide a base functionality. This base functionality can be further enhanced by incremental units.

Such discretisation results in the definition of various types of logical units of applications/packages.

to do

Include graphical illustration of core, modules, extensions, add-on, plugin along with base functionality, extended functionality and features

Files draft

Description of files here

LICENSE
A plain text file containing the licence with the name of the copyright holder
VERSION

A plain text file containing the version number of the package.

Quickstart

A plain text file containing a brief guide to get started.

This is typically the README.md file in most packages. If the application is small then this may contain the complete documentation.

Code

Files and folders as per the structure of the software/library

Use of the directory structure described later is highly encouraged.

Directory layout of different applications and packages vary however the approach used is very similar.

Example directory structure

Project directory

  • LICENSE
  • VERSION
  • CHANGELOG
  • Config
    • fl_App.config.inc.ext
    • fl_Plugin.config.inc.ext
    • ...
  • Lib
    • fl_Common.function.inc.php
    • fl_Specific.class.inc.php
    • ...
  • Module
    • Render_Template
      • fl_Render_Smarty.module.inc.php
      • ...
    • Scraper_Tvdb
      • fl_Scraper_Tvdb.module.inc.php
      • ...

Layout to do

Typical structure of a file. Variable declarations, function definitions, etc.

Variable organisation wip

As the development of a project progresses, the various mathematical steps, logical routines and control structures will inevitable leave behind a significant number of variables. This can result in considerable disorganisation of used and unused variables in memory. Unfortunately this variable "spread" cannot be predicted or planned before project kick-off, as most of the variables are a result of evolved development.

It is therefore essential to re-evaluate the organisation of variables to ensure they are controlled and organised, to ensure a tidy code structure.

Variables can be broadly organised into the following categories. Each of the categories may leverage the variable structure formulation of coding language used. The most typical of this is the array construct.

Configuration
A collection of variables representing the configuration of the project/programme/code base.
State
A collection of variables representing the state of various aspects of the code base.
Exchange
Collections of variables for data exchange between modules

Configuration variables

Configuration variables represent the configuration of the application and can be organised either by the "changeability" of the configuration or by application architecture (modules, etc.).

Constant configuration
Per instance. Install-time.
Static configuration
Per session. pre-run
Dynamic configuration
Run time configuration. Per page or per view
Active configuration
Run time configuration, actively changeable.

State variables

This collection of variables can be utilised various aspects of the core code or modules to check the status or state of either configuration flags or any specific requirements

Exchange variables

Exchange variables are used to specifically exchange data, either take input, provide output or pass data between modules or other language constructs.

This is particularly useful when randomly picking existing variables for exchange may introduce confusion and potential security threats.

Input variables

A collection of variables representing input data for processing (sanitised, if necessary).

Response variables

A collection of variables representing response to an action so this may be handed off (redacted, if necessary).

This collection of variables can be utilised to store response or responses from functions, classes or other logic structures, so that the outcome of processing can be carried out in isolation.

Other

There some additional variable collection which may be added by contexts
UI
A collection to hand-off to UI, especially in MVC-modelled codebases.

Formatting wip

Description of formatting here

  • 80 columns wide lines is a generic viewport

Whitespace wip

Liberal but optimal use of whitespace, both horizontal and vertical.

Horizontal wip
Indent draft

Indenting code is essential to cleanly convey the logic and approach used in developing the application. The exception to this is the formatting restrictions imposed by the language used to write the code.

Logical indentation refers to the indentation used in the code to depict logical hierarchy; e.g., nested loops, functions, classes and methods.

This is unambiguous and provides a clear view of the hierarchy. There are however certain descretions that can be taken to ensure clean code. These descretions are in cases were hierarchical child objects are small enough to need a line for themselves, hence included in the same line as their heirarchical parent, as shown in the following example of a single line of repeating code in PHP which also contributes to the modular approach.

fn_Debug($sr_Check){echo('<pre>'.$sr_Check.'</pre>');}

Overflow indentation refers to the hanging indentation used in the code to depict continuation of a statement from the preceding line. This is primarily done to ensure that the overall width of lines does not exceed the conservative 80-character width of the generic view port

There are two alternatives to clean represent such continuation.

Contextual hanging indent

Width of indentation in this case is decided by the point at which the item continued on the new line is started; shown by the following example

if ( !array_key_exists ( 'ky_LdapVer' , $this->ar_Dir['ky_Conf'] ) |
     $this->ar_Dir['ky_Conf']['ky_LdapVer'] == ''
     ) {
  $this->ar_Dir['ky_Conf']['ky_LdapVer'] = 3 ;
}

Fixed hanging indent

Width of indentation in this case is decided by the chosen width used for global logical indentation; shown by the following example. In this case the continued code on the overflow line is treated as a heirarchical child of the line on which the overflowing statement started.

if ( !array_key_exists ( 'ky_LdapVer' , $this->ar_Dir['ky_Conf'] ) |
  $this->ar_Dir['ky_Conf']['ky_LdapVer'] == ''
  ) {
  $this->ar_Dir['ky_Conf']['ky_LdapVer'] = 3 ;
}
Intra-line space to do
Vertical to do

Semantics draft

Coding semantics play an important role in making the entire code consistent. If this practice is applied across teams and languages, Large pieces of code can be easily understood. Various aspects of coding fall under semantics; these can be logical variables, values, database tables, fields or even filesystem objects like files and directories. For the purpose of this document, each of these aspect will be referred to as an item.

Formulation

The semantic formulation of an item name involves splitting it into two distinct parts.

Type prefix
A two character prefix indicating the type of item
Item name
Rational name of the item
Type prefix
Two characters, both lower case, describing the type of item, variable or object. Two characters provide 676 unique combinations, so should be plenty. Selection of these two characters is made by using the first two consonants in the type name. If already used, then the first and the third, and so on.
Item name
A short but descriptive name of the item, variable or object. Avoid abbreviations and standard names from language documentation. Use CamelCase for multi-word names. Use shorter forms of common words.

Examples

The following examples illustrate the formulation of an item name/reference in various contexts.

Logic

Logic items include variables, objects and logic routines like classes, functions, methods and objects.

Numerical variable (integer, float, etc.)
Boolean variable (true/false, yes/no, 1/0, etc. )
String variable (including numeric characters)
Argument supplied to a function/method
Return variable (all types including arrays, integer, float, etc.)
Array variable (both associative and non-associative)
Key for arrays (specifically for associative types).
There is still a question whether all arrays should be prefixed with ky_ or with the type of variable they are. This is open for discussion.
Function or method
Class definitions
Object instance of class
Unspecified variable type or category.
User interface

User interface items include UI elements, frames, buttons and other hidden elements like div elements.

Button, either aesthetic or for forms.
Text box or field for forms.
Label elements.
Check box element.
Radio button element.
Tabbed section container.
Tab page (usually inside a tabbed section container).
Division (div) element, usually found in HTML.
Image element.
Link element. This could be reference to a symbolic link, its container or a URL.
Combo box, usually rendered as an on-demand drop-down list.
Depending on the application environment and the coding language used, this could be reference to a file, sub-routine or a sub-system relating to reporting.
In database programming, this could be a saved report template.
Frame could refer either a container for other UI elements or a sectioned division of the rendered viewport.
Databases

Database include databases, users, tables, fields, etc.

Database reference.
User, also usable in non-database context.
Database password, also can be utilised elsewhere.
Table, also can be used for interface elements rendered as tables.
Database fields.
Junction or map tables (commonly used for many-to-many relationships in RDBMS).
Lookups (usually tables).
Database queries.
File system

Filesystem items include objects like files, directories, sockets, PID files, etc.

File object, used to reference or to store paths to file objects.
Directory object, used to reference or to store directory paths.

Testing to do

Description of testing here

Documenting wip

Documentation of both code is essential for clean, collaborative and scalable code.

Similarly documentation of the application is essential for mapping usability and functionality to the functional logic and critically, the caveats. It is due to such caveats that the best practice is to document the code concurrent to coding and testing.

Packaging to do

Description of Packaging here