Coding best practices

A software development methodology is a framework that is used to structure, plan, and control the life cycle of a software product. Common methodologies include waterfall, prototyping, iterative and incremental development, spiral development, agile software development, rapid application development, and extreme programming.

The waterfall model is a sequential development approach; in particular, it assumes that the requirements can be completely defined at the start of a project. However, McConnell quotes three studies that indicate that, on average, requirements change by around 25% during a project.[9] The other methodologies mentioned above all attempt to reduce the impact of such requirement changes, often by some form of step-wise, incremental, or iterative approach. Different methodologies may be appropriate for different development environments.

Since its introduction in 2001, agile software development has grown in popularity, fueled by software developers seeking a more iterative, collaborative approach to software development.[10]

McConnell states: "The first prerequisite you need to fulfill before beginning construction is a clear statement of the problem the system is supposed to solve."[11]

Meek and Heath emphasise that a clear, complete, precise, and unambiguous written specification is the target to aim for.[12] Note that it may not be possible to achieve this target, and the target is likely to change anyway (as mentioned in the previous section).

Sommerville distinguishes between less detailed user requirements and more detailed system requirements.[13] He also distinguishes between functional requirements (e.g. update a record) and non-functional requirements (e.g. response time must be less than 1 second).

Hoare points out: "there are two ways of constructing a software design: one way is to make it so simple that there are obviously no deficiencies; the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult."[14]

Software architecture is concerned with deciding what has to be done and which program component is going to do it (how something is done is left to the detailed design phase below). This is particularly important when a software system contains more than one program since it effectively defines the interface between these various programs. It should include some consideration of any user interfaces as well, without going into excessive detail.

Any non-functional system requirements (response time, reliability, maintainability, etc.) need to be considered at this stage.[15]

The software architecture is also of interest to various stakeholders (sponsors, end-users, etc.) since it gives them a chance to check that their requirements can be met.

The primary purpose of design is to fill in the details which have been glossed over in the architectural design. The intention is that the design should be detailed enough to provide a good guide for actual coding, including details of any particular algorithms to be used. For example, at the architectural level, it may have been noted that some data has to be sorted, while at the design level, it is necessary to decide which sorting algorithm is to be used. As a further example, if an object-oriented approach is being used, then the details of the objects must be determined (attributes and methods).

Mayer states: "No programming language is perfect. There is not even a single best language; there are only languages well suited or perhaps poorly suited for particular purposes. Understanding the problem and associated programming requirements is necessary for choosing the language best suited for the solution."[16]

From Meek & Heath: "The essence of the art of choosing a language is to start with the problem, decide what its requirements are, and their relative importance since it will probably be impossible to satisfy them all equally well. The available languages should then be measured against the list of requirements, and the most suitable (or least unsatisfactory) chosen."[17]

It is possible that different programming languages may be appropriate for different aspects of the problem. If the languages or their compilers permit, it may be feasible to mix routines written in different languages within the same program.

Even if there is no choice as to which programming language is to be used, McConnell provides some advice: "Every programming language has strengths and weaknesses. Be aware of the specific strengths and weaknesses of the language you're using."[18]

Due to time restrictions or enthusiastic programmers who want immediate results for their code, commenting of code often takes a back seat. Programmers working as a team have found it better to leave comments behind since coding usually follows cycles, or more than one person may work on a particular module. However, some commenting can decrease the cost of knowledge transfer between developers working on the same module.

In the early days of computing, one commenting practice was to leave a brief description of the following:

1. Name of the module
2. Purpose of the Module
3. Description of the Module
4. Original Author
5. Modifications
6. Authors who modified code with a description on why it was modified.

The "description of the module" should be as brief as possible but without sacrificing clarity and comprehensiveness.

However, the last two items have largely been obsoleted by the advent of revision control systems. Modifications and their authorship can be reliably tracked by using such tools rather than by using comments.

Also, if complicated logic is being used, it is a good practice to leave a comment "block" near that part so that another programmer can understand what exactly is happening.

Unit testing can be another way to show how code is intended to be used.

Use of proper naming conventions is considered good practice. Sometimes programmers tend to use X1, Y1, etc. as variables and forget to replace them with meaningful ones, causing confusion.

It is usually considered good practice to use descriptive names.

Example: A variable for taking in weight as a parameter for a truck can be named TrkWeight or TruckWeightKilograms, with TruckWeightKilograms being the preferable one since it is instantly recognisable. See CamelCase naming of variables.

The code that a programmer writes should be simple. Complicated logic for achieving a simple thing should be kept to a minimum since the code might be modified by another programmer in the future. The logic one programmer implemented may not make perfect sense to another. So, always keep the code as simple as possible.[20]

For example, consider these equivalent lines of C code:

if (hours < 24 && minutes < 60 && seconds < 60)
{
    return true;
}
else
{
    return false;
}

and

if (hours < 24 && minutes < 60 && seconds < 60)
    return true;
else
    return false;

and

switch (hours < 24 && minutes < 60 && seconds < 60){
    case true:
        return true;
    break;
    case false:
        return false;
    break;
    default:
        return false;
}

and

return hours < 24 && minutes < 60 && seconds < 60;

The 1st approach, which is much more commonly used, is considerably larger than the 4th. In particular, it consumes 5 times more screen vertical space (lines), and 97 characters versus 52 (though editing tools may reduce the difference in actual typing). It is arguable, however, which is "simpler". The first has an explicit if/then else, with an explicit return value obviously connected with each; even a novice programmer should have no difficulty understanding it. The 2nd merely discards the braces, cutting the "vertical" size in half with little change in conceptual complexity. In most languages, the "return" statements could also be appended to the prior lines, bringing the "vertical" size to only one more line than the 4th form.

The fourth form obviously minimizes the size but may increase the complexity: It leaves the "true" and "false" values implicit, and intermixes the notions of "condition" and "return value". It is likely obvious to most programmers, but a novice might not immediately understand that the result of evaluating a condition is actually a value (of type Boolean or its equivalent in whatever language), and thus can be manipulated or returned. In more realistic examples, the 4th form could have problems due to operator precedence, perhaps returning an unexpected type, where the prior forms would, in some languages, report an error. Thus, "simplicity" is not merely a matter of length, but of logical and conceptual structure; making code shorter may make it less or more complex.

For large, long lived programs using verbose alternatives could contribute to bloat.

Compactness can allow coders to view more code per page, reducing scrolling gestures and keystrokes. Given how many times code might be viewed in the process of writing and maintaining, it might amount to a significant savings in programmer keystrokes in the life of the code. This might not seem significant to a student first learning to program but, when producing and maintaining large programs the reduction of how many lines of code there are allows for more of the code to fit on screen, minor code simplification may improve productivity, and also lessen finger, wrist and eye strain, which are common medical issues suffered by production coders and information workers.[21]

Terser coding speeds compilation very slightly, as fewer symbols need to be processed. Furthermore, the 3rd approach may allow similar lines of code to be more easily compared, particularly when many such constructs can appear on one screen at the same time.

Finally, very terse layouts may better utilize modern wide-screen computer displays, depending on monitor layout and setup. In the past, screens were limited to 40 or 80 characters (such limits originated far earlier: manuscripts, printed books, and even scrolls, have for millennia used quite short lines (see for example Gutenberg Bible). Modern screens can easily display 200 or more characters, allowing extremely long lines. Most modern coding styles and standards do not take up that entire width. Thus, if using one window as wide as the screen, a great deal of available space is wasted. On the other hand, with multiple windows, or using an IDE or other tool with various information in side panes, the available width for code is in the range familiar from earlier systems.

It is also worth noting that the human visual system is greatly affected by line length; very long lines slightly increase reading speed, but reduce comprehension Text Columns: How Long is Too Long? and add to eye-tracking errors. Some studies suggest that longer lines fare better online than in print Human Factors International, but this still only goes up to about 10 inches, and mainly for raw speed of reading prose.

Program code should not contain "hard-coded" (literal) values referring to environmental parameters, such as absolute file paths, file names, user names, host names, IP addresses, and URLs, UDP/TCP ports. Otherwise, the application will not run on a host that has a different design than anticipated. A careful programmer can parametrize such variables and configure them for the hosting environment outside of the application proper (for example, in property files, on an application server, or even in a database). Compare the mantra of a "single point of definition"[22] (SPOD).

As an extension, resources such as XML files should also contain variables rather than literal values, otherwise, the application will not be portable to another environment without editing the XML files. For example, with J2EE applications running in an application server, such environmental parameters can be defined in the scope of the JVM, and the application should get the values from there.

Design code with scalability as a design goal because very often in software projects, new features are always added to a project which becomes bigger. Therefore, the facility to add new features to a software code base becomes an invaluable method in writing software.

Re-use is a very important design goal in software development. Re-use cuts development costs and also reduces the time for development if the components or modules which are reused are already tested. Very often, software projects start with an existing baseline that contains the project in its prior version and depending on the project, many of existing software modules and components are reused, which reduces development and testing time, therefore, increasing the probability of delivering a software project on schedule.

A general overview of all of the above:

1. Know what the code block must perform
2. Maintain naming conventions which are uniform throughout.
3. Indicate a brief description of what a variable is for (reference to commenting)
4. Correct errors as they occur.
5. Keep your code simple
6. Design code with scalability and reuse in mind.

A best practice for building code involves daily builds and testing, or better still continuous integration, or even continuous delivery.

Testing is an integral part of software development that needs to be planned. It is also important that testing is done proactively; meaning that test cases are planned before coding starts, and test cases are developed while the application is being designed and coded.

Programmers tend to write the complete code and then begin debugging and checking for errors. Though this approach can save time in smaller projects, bigger and more complex ones tend to have too many variables and functions that need attention. Therefore, it is good to debug every module once you are done and not the entire program. This saves time in the long run so that one does not end up wasting a lot of time on figuring out what is wrong. Unit tests for individual modules and/or functional tests for web services and web applications can help with this.

Deployment is the final stage of releasing an application for users. Some best practices are:[23][24]

1. Keep the installation structure simple: Files and directories should be kept to a minimum. Don’t install anything that’s never going to be used.
2. Keep only what is needed: The software configuration management activities must make sure this is enforced. Unused resources (old or failed versions of files, source code, interfaces, etc.) must be archived somewhere else to keep newer builds lean.
3. Keep everything updated: The software configuration management activities must make sure this is enforced. For delta-based deployments, make sure the versions of the resources that are already deployed are the latest before deploying the deltas. If not sure, perform a deployment from scratch (delete everything first and then re-deploy).
4. Adopt a multi-stage strategy: Depending on the size of the project, sometimes more deployments are needed.[25]
5. Have a roll back strategy: There must be a way to roll-back to a previous (working) version.
6. Rely on automation for repeatable processes: There's far too much room for human error, deployments should not be manual. Use a tool that is native to each operating system or, use a scripting language for cross-platform deployments.[26][27]
7. Re-create the real deployment environment: Consider everything (routers, firewalls, web servers, web browsers, file systems, etc.)
8. Do not change deployment procedures and scripts on-the-fly and, document such changes: Wait for a new iteration and record such changes appropriately.
9. Customize deployment: Newer software products such as APIs, micro-services, etc. require specific considerations for successful deployment.[28][29][30]
10. Reduce risk from other development phases: If other activities such as testing and configuration management are wrong, deployment surely will fail.[31][32]
11. Consider the influence each stakeholder has: Organizational, social, governmental considerations.[33][34][35]