Coding Guidelines in Software Engineering

Writing an efficient software code requires a thorough knowledge of programming. This knowledge can be implemented by following a coding style which comprises several guidelines that help in writing the software code efficiently and with minimum errors. These guidelines, known as coding guidelines, are used to implement individual programming language constructs, comments, formatting, and so on. These guidelines, if followed, help in preventing errors, controlling the complexity of the program, and increasing the readability and understandability of the program.

A set of comprehensive coding guidelines encompasses all aspects of code development. To ensure that all developers work in a harmonized manner (the source code should reflect a harmonized style as a single developer had written the entire code in one session), the developers should be aware of the coding guidelines before starting a software project. Moreover, coding guidelines should state how to deal with the existing code when the software incorporates it or when maintenance is performed.

Since there are numerous programming languages for writing software codes, each having different features and capabilities, coding style guidelines differ from one language to another. However, there are some basic guidelines which are followed in all programming languages. These include naming conventions, commenting conventions, and formatting conventions.

There are certain rules for naming variables, functions and methods in the software code. These naming conventions help software; developers in understanding the use of a particular variable or function. The guidelines used to assign a name to any variable, function, and method are listed below.

• All the variables, functions, and methods should be assigned names that make the code more understandable to the reader. By using meaningful names, the code can be self-explanatory, thus, minimizing the effort of writing comments for variables. For example, if two variables are required to refer to ‘sales tax’ and ‘income tax’, they should be assigned names such as ‘sales Tax’ and ‘income Tax’.
• For names, a full description in a commonly spoken language (for example, English) should be used. In addition, the use of abbreviations should be avoided. For example, variable names like ‘contact Number’ and ‘address’ should be used instead of ‘cno’ and ‘add’.
• Short and clear names should be assigned in place of long names. For ‘example, ‘multiply The Two Numbers’ can be shortened to ‘multiply Numbers’ as it is clear and short enough to be expressed in reasonable length.

In every programming language, there is a different naming convention for variables and constants in the software code. The commonly used conventions for naming variables and constants are listed in Table.

                 Table  Naming Conventions for Variables and Constants

As with variables and constants, there are some guidelines that should be followed while naming functions in the software code. These conventions are listed below.

• The names of functions should be meaningful and should describe the purpose of the function with clarity and briefness. Like variables, the names should be self-explanatory so that no additional description about the task of that function is required.
• The function name should begin with a verb. For example, the verb ‘display’ can be used for the function that displays the output on the screen. In case the verb itself is not descriptive, an additional noun or adjective can be used with the verb. For example, the function name ‘add Marks’ should be used to clarify the function and its purpose.
• In case the function returns a Boolean value, the helping verbs ‘is’ and ‘has’ should be used as prefixes for the function name. For example, the function name ‘is Deposited’ or ‘has Deposited’ should be used for functions that return true or false values.

Comments are helpful in proper understanding of the code segment used in program. Commenting conventions should be used efficiently to make the code easy to grasp. Generally, two types of commenting conventions are used: file header comments and trailing comments.

File header comments are useful in providing information related to a file as a whole and comprise identification information such as date of creation, Dame of the creator, and a brief description of the software code.

Trailing comments are used to provide explanation of a single line of code. These comments are used to clarify the complex code. These also specify the function of the abbreviated variable names that are not clear. In some languages, trailing comments are used with the help of a double slash (//). The commenting conventions that are commonly followed in the software code are listed below.

• Comments should not be used to include information that is clearly understandable from the software.
• Comments should be used with important segments of code and code segments that are difficult to understand.
• Comments should be separated from the code to enhance readability of the software code.

Formatting (way of arranging a program in order to enhance readability) consists of indentation, alignment, and use of white spaces in the program. Consistency plays an important role while formatting a program in an organized way. A program with consistent formatting makes the code easier to read and understand. The commonly used formatting conventions are listed below.

• Indentation: This refers to one or more spaces left at the beginning of statements in the program. Indentation is useful in making the code easily readable. However, the spaces used for indentation should be followed in the entire program. The guidelines that are commonly followed while indenting a program are listed below.White spaces: These improve readability by minimizing the compactness of the code. Some of the guidelines for proper usage of spaces within the code are listed below.
  • Indentation should be used to highlight a nested block. Some nested blocks can be made with the help of ‘if-else’ and ‘do-while’ loops.
  • Indentation is required if the statement is large enough to fit in a single line.
  • Indentation should be consistent at the beginning and at the end of the braces in the program.

• There should be a space after placing a comma between two function arguments.
• There should be no space between a function name and parenthesis.
• There should be spaces to align the operators vertically to emphasize program structure and semantics.

 Implementing Coding Guidelines

If coding guidelines are used in a proper manner, errors can be detected at the time of writing the software code. Such detection in early stages helps in increasing the performance of the software as well as reducing the additional and unplanned costs of correcting and removing errors. Moreover, if a well-defined coding guideline is applied, the program yields a software system that is easy to comprehend and maintain. Some of the coding guidelines that are followed in a programming language are listed below.

• All the codes should be properly commented before being submitted to the review team.
• All curly braces should start from a new line.
• All class names should start with the abbreviation of each group. For example, AA and CM can be used instead of academic administration and course management, respectively.
• Errors should be mentioned in the following format: [error code]: [explanation]. For example, 0102: null pointer exception, where 0102 indicates the error code and null pointer exception is the name of the error.
• Every ‘if statement should be followed by a curly braces even if there exists only a single statement.
• Every file should contain information about the author of the file, modification date, and version information.

Similarly, some of the commonly used coding guidelines in a database (organized collection of information that is systematically organized for easy access and analysis) are listed below.

• Table names should start with TBL. For example, TBL_STUDENT.
• If table names contain one word, field names should start with the first three characters of the name of the table. For example, STU_FIRSTNAME.
• Every table should have a primary key.
• Long data type (or database equivalent) should be used for the primary key.

Advantages of Coding Guidelines

Coding guidelines supplement the language standard by defining acceptable and unacceptable usage of the programming language used. Acceptable usage avoids troublesome situations while unacceptable usage is conducive to errors or leads to misunderstanding of the written code. Properly implemented coding guidelines help the developer to limit program complexity, establish the basis for code review, and guard against compiler and common programming errors. Other advantages associated with coding guidelines are listed below and depicted.

• Increased efficiency: Coding guidelines can be used effectively to save time spent on gathering unnecessary details. These guidelines increase the efficiency of the software team while the software development phase is carried out. An efficient software code is fast and economical. Software coding guidelines are used to increase efficiency by making the team productive, thus, ensuring that the software is delivered to the user on time.
• Reduced costs: Coding guidelines are beneficial in reducing the cost incurred on the software project. This is possible since coding guidelines help in detecting errors in the early stages of the software development. Note that if errors are discovered after the software is delivered to the user, the process of rectifying them becomes expensive as additional costs are incurred on late detection, rework, and retesting of the entire software code.
• Reduced complexity: The written software code can be either simple or complex. Generally, it is observed that a complex segment of software code is more susceptible to errors than a segment containing a simple software code. This is because a complex software code reduces readability as well as understandability. In addition, the complex software code may be inefficient in functioning and use of resources. However, if the code is written using the given coding guidelines, the problem of complexity can be significantly avoided as the probability of error occurrence reduces substantially.
• Reduced hidden costs: Coding guidelines, if adhered to in a proper manner, help to achieve a high-quality software code. The software quality determines the efficiency of the software. Software quality is the degree to which user requirements are accomplished in the software along with conformity to standards. Note that if quality is not considered while developing the software, the cost for activities such as fixing errors, redesigning the software, and providing technical support increases considerably.
• Code reuse: Using coding guidelines, software developers are able to write a code that is more robust and create individual modules of the software code. The reason for making separate code segment is to enable reusability of the modules used in the software. A reusable module can be used a number of times in different modules in one or more software.
• Automated error prevention: The coding guidelines enable Automated Error Prevention (AEP).This assures that each time error occurs in software, the software development activity is improved to prevent similar errors in future. AEP begins with detecting errors in the software, isolating its cause, and then searching the cause of error generation. Coding guidelines are useful in preventing errors as they allow implementation of requirements that prevent the most common and damaging errors in the software code.

In addition to the above mentioned advantages, coding guidelines define appropriate metric thresholds. These thresholds help in reducing complexity, thus, minimizing the occurrence of errors. Software developers face increasing demands to demonstrate that development practices meet the accepted coding guidelines. This is essential for companies developing safety-critical software as well as those seeking CMM and ISO certification.