Programming Style Guides and Coding

Standards
Contents
• Programming Style Guides and Coding Standards
• Literate Programming and Software Documentation
• Document Generators
• Javadoc
• phpDocumentor
Programming Style Guides
• Programming Style/ Code Style
• Set of rules or guidelines used when writing the source
code for a computer program
• A style guide helps everyone to write code in a consistent
way, and consistent code is easier to read and faster to
update
• The goal of good programming style is to provide
understandable, straightforward, elegant code
Programming Style - General Guidlines
• Clarity and simplicity of Expression
• The programs should be designed in such a manner so that the objectives of
the program is clear
• Naming
• In a program, it is required to name the module, processes, variable and so
on. The naming style should not be cryptic and non-representative
Ex. a = 3.14 * r * r
area of circle = 3.14 * radius * radius;
• Control Constructs
• It is desirable that as much as a possible single entry and single exit constructs
used
Programming Style - General Guidelines
• Information hiding
• The information stored in the data structures should be hidden from the rest
of the system where possible. Information hiding can decrease the coupling
between modules and make the system more maintainable
• Nesting
• It is desirable to avoid deep nesting of loops and conditions. Deep nesting
harm the static and dynamic behavior of a program. It also becomes difficult
to understand the program logic
• User-defined types
• Make heavy use of user-defined data types like enum, class, structure, and
union. These data types make the program code easy to write and easy to
understand
Programming Style - General Guidelines
• Module size
• The module size should be uniform. The size of the module should
not be too big or too small. If the module size is too large, it is not
generally functionally cohesive. If the module size is too small, it
leads to unnecessary overheads.
• Module Interface
• A module with a complex interface should be carefully examined
• Side-effects
• When a module is invoked, it sometimes has a side effect of
modifying the program state. Such side-effect should be avoided
• Widely accepted style guides
• Google’s Style Guides
• JavaScript Standard Style
• GitHub’s Ruby Style Guide
• Python Foundation’s Style Guide
• Airbnb’s JavaScript Style Guide
• Angular’s Style Guide
Coding Standards

• Coding standards are a set of guidelines and best practices

that are used to create consistent, high-quality code
• The rules and techniques helps to develop cleaner, more
readable, and more efficient code with minimal errors

• They offer a uniform format for software engineers to build

sophisticated and highly functional code
Coding Standards

• Good software development organizations want their

programmers to maintain to some well-defined and standard
style of coding called coding standards
• They usually make their own coding standards and guidelines
depending on what suits their organization best and based
on the types of software they develop
• It is very important for the programmers to maintain the
coding standards otherwise the code will be rejected during
code review
Coding Standards - Purpose

• Improves code quality

• Gives a uniform appearance to the codes written by different
engineers
• Readability, and maintainability of the code is improved and
complexity is reduced
• Facilitate Collaboration
• It creates a common language that all developers can understand
and allows teams to collaborate, share code, and communicate
effectively
Coding Standards - Purpose

• Increase Efficiency
• By following coding standards, developers can save time by
avoiding common mistakes and implementing proven solutions
• Ensure compatibility
• Ensures that code is compatible with different platforms, browsers,
and OS-device combinations
• Reduce Maintenance Costs
• By following established standards, developers can avoid
introducing new bugs and make changes to code more quickly and
easily
Coding Standards - General Guidelines

• Limited use of globals

• Standard headers for different modules
• For better understanding and maintenance of the code, the header of
different modules should follow some standard format and information. The
header format must contain below things that is being used in various
companies:
• Name of the module
• Date of module creation
• Author of the module
• Modification history
• Synopsis of the module about what the module does
• Different functions supported in the module along with their input output parameters
• Global variables accessed or modified by the module
Coding Standards - General Guidelines
•Naming conventions for local variables, global variables, constants
and functions
•Some of the naming conventions are given below:
•Meaningful and understandable variables name helps anyone to
understand the reason of using it
•Local variables should be named using camel case lettering starting with
small letter (e.g. localData) whereas Global variables names should start
with a capital letter (e.g. GlobalData). Constant names should be formed
using capital letters only (e.g. CONSDATA)
•It is better to avoid the use of digits in variable names
•The names of the function should be written in camel case starting with
small letters.
•The name of the function must describe the reason of using the function
clearly and briefly
Coding Standards - General Guidelines
• Indentation
• Proper indentation and proper use of white spaces are very important to
increase the readability of the code
• Some of the spacing conventions are
•There must be a space after giving a comma between two function arguments
•Each nested block should be properly indented and spaced
•Proper Indentation should be there at the beginning and at the end of each block in
the program
•All braces should start from a new line and the code following the end of braces also
start from a new line

• Error return values and exception handling conventions

• All the functions encountering an error condition should either return a 0
or 1 for simplifying the debugging
Coding Standards - General Guidelines
• Avoid using a coding style that is too difficult to understand
• Code should be easily understandable. The complex code makes
maintenance and debugging difficult and expensive

• Avoid using an identifier for multiple purposes

• Each variable should be given a descriptive and meaningful name
indicating the reason behind using it. This is not possible if an
identifier is used for multiple purposes and thus it can lead to
confusion to the reader. Moreover, it leads to more difficulty
during future enhancements.
Coding Standards - General Guidelines

• Code should be well documented

• The code should be properly commented for understanding easily

• Length of functions should not be very large

• Lengthy functions are very difficult to understand
• Lengthy functions should be broken into small ones for completing small tasks

• Try not to use GOTO statement

• GOTO statement makes the program unstructured, thus it reduces the
understandability of the program and also debugging becomes difficult
Advantages of Coding Standards
• Coding guidelines increases the efficiency of the software and
reduces the development time
• Helps in detecting errors in the early phases
• Increases readability and understandability thus it reduces the
complexity of the code
• It reduces the hidden cost for developing the software
• Compliance with industry standards (ex. ISO)
• Consistent code quality — no matter who writes the code
• Software security from the start
• Reduced development costs
Literate Programming
• Introduced by Donald Knuth in 1984

• Literate programming is a programming methodology that

combines a programming language with a documentation
language
• Makes programs more robust, more portable, and more easily
maintained than programs written only in a high-level language

• The main idea is to treat a program as a piece of literature,

addressed to human beings rather than to a computer
Literate Programming

• When programs are written in the recommended style they

can be transformed into documents by a document compiler
and into efficient code by an algebraic compiler
• Implementing literate programming consists of two steps
• Weaving
• Generating comprehensive document about program
and its maintenance
• Tangling
• Generating machine executable code
Advantages
• Provides higher-quality programs, since it forces programmers to
explicitly state the thoughts behind the program
• Provides a first-rate documentation system, which is not an add-on,
but is grown naturally in the process of exposition of one's thoughts
during a program's creation
• Allows other programmers to understand the construction of the
program more easily
• Can lead to easy porting of software to multiple environment
Software Documentation

• Software documentation is a written material, images, or video

instructions that comes with computer software. It explains how to use a
program or a service
• The documentation helps keep track of all aspects of an application and it
improves the quality of a software product. Its main focuses are
development, maintenance and knowledge transfer to other developers
• Successful documentation will make information easily accessible, provide
a limited number of user entry points, help new users learn quickly,
simplify the product and helps to cut support costs
• A well written document provides a tool and means of information
repository
Software Documentation

• A well maintained documentation should involve the

following documents
• Requirement Documentation

• Software Design Documentation

• Technical Documentation

• User Documentation
Advantages of Documentation
• Keeps track of all parts of a software or program
• Maintenance is easier
• Programmers other than the developer can understand all aspects of
software
• Improves overall quality of the software
• Assists in user training
• Ensures knowledge de-centralization, cutting costs and effort if people
leave the system abruptly
Documentation Generators
• A documentation generator is a programming tool that generates
software documentation intended for programmers or end users or
both, from a set of source code files, and in some cases, binary files
• Types of generation
• Batch generation (generic technique)
• Text block correspondence (documents created based on pre-defined text
blocks)
• Forms (forms for websites)
• Documentation synthesis:
• Documentation can be inferred from code
• Documentation can be inferred from execution traces
Javadoc & phpDocumentor
• Javadoc
• Is a documentation generator created by Sun Microsystems for the
Java language (now owned by Oracle Corporation) for generating
API documentation in HTML format from Java source code
• The HTML format is used for adding the convenience of being able
to hyperlink related documents together
• phpDocumentor
• Is the de-facto documentation application for PHP projects
• The phpDocumentor package provides automatic documenting of
php api directly from the source