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.
Fundamental concepts
Library of assets, further categorised into types.
Reusable code
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.
Include graphical illustration of core, modules, extensions, add-on, plugin along with base functionality, extended functionality and features
Description of files here
A plain text file containing the version number of the package.
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.
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.
Project directory
Typical structure of a file. Variable declarations, function definitions, etc.
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 variables represent the configuration of the application and can be organised either by the "changeability" of the configuration or by application architecture (modules, etc.).
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 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.
A collection of variables representing input data for processing (sanitised, if necessary).
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.
Description of formatting here
Liberal but optimal use of whitespace, both horizontal and vertical.
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.
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 ;
}
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 ;
}
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.
The semantic formulation of an item name involves splitting it into two distinct parts.
The following examples illustrate the formulation of an item name/reference in various contexts.
Logic items include variables, objects and logic routines like classes, functions, methods and objects.
ky_
or with the type of variable they are. This is open for discussion.
User interface items include UI elements, frames, buttons and other hidden elements like div
elements.
Database include databases, users, tables, fields, etc.
sr_Fieldname
for fields containing string variable typesnm_Fieldname
for fields containing numeric variable typesbl_Fieldname
for fields containing boolean variable typesFor mixed or undefined field types fd_FieldName
can be used as a fall-back.
Filesystem items include objects like files, directories, sockets, PID files, etc.
Description of testing here
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.
Description of Packaging here
There is also a good document at drupal.org for...
The GNU project specifies coding standards for GNU programs.
Although these standards allude to programs mainly written in the C language, some of the disciplinary aspects of these standards are relevant to those covered in this documents.
Books and other reading material