SE 386 Software Maintenance and Reengineering
Notes 006- Coding Standards
1 Coding Standards
Coding standards can dramatically decrease the cost of maintenance.
From Microsoft: http://msdn.microsoft.com/library/default.asp?url=/library/enus/vsent7/html/vxconCodingStandardsCodeReviews.asp
Key parts:
1. Developers should prudently strive to implement to a standard, the standard should be
adhered to whenever practical
2. At the inception of a software project, establish a coding standard to ensure that all developers
on the project are working in concert
3. The easiest method to ensure a team of developers will yield quality code is to establish a
coding standard, which is then enforced at routine code reviews.
4. Using solid coding techniques and good programming practices to create high-quality code
plays an important role in software quality and performance.
a. In addition, if you consistently apply a well-defined coding standard, apply proper
coding techniques, and subsequently hold routine code reviews, a software project is
more likely to yield a software system that is easy to comprehend and maintain.
5. Adherence to a coding standard is only feasible when followed throughout the software project
from inception to completion.
Direct from Microsoft:
A comprehensive coding standard encompasses all aspects of code construction. While developers
should prudently implement a standard, it should be adhered to whenever practical. Completed source
code should reflect a harmonized style, as if a single developer wrote the code in one session. At the
inception of a software project, establish a coding standard to ensure that all developers on the project
are working in concert. When the software project incorporates existing source code, or when
performing maintenance on an existing software system, the coding standard should state how to deal
with the existing code base.
The readability of source code has a direct impact on how well a developer comprehends a software
system. Code maintainability refers to how easily that software system can be changed to add new
features, modify existing features, fix bugs, or improve performance. Although readability and
maintainability are the result of many factors, one particular facet of software development upon
which all developers have an influence is coding technique. The easiest method to ensure a team of
developers will yield quality code is to establish a coding standard, which is then enforced at routine
code reviews. Using solid coding techniques and good programming practices to create high-quality
code plays an important role in software quality and performance. In addition, if you consistently apply
a well-defined coding standard, apply proper coding techniques, and subsequently hold routine code
©2012 Mike Rowe
Page 1
2/8/2016 4:11:00 PM
SE 386 Software Maintenance and Reengineering
Notes 006- Coding Standards
reviews, a software project is more likely to yield a software system that is easy to comprehend and
maintain.
Although the primary purpose for conducting code reviews throughout the development life cycle is to
identify defects in the code, the reviews can also enforce coding standards in a uniform manner.
Adherence to a coding standard is only feasible when followed throughout the software project from
inception to completion. It is not practical, nor is it prudent, to impose a coding standard after the fact.
1.1 Code Style and Code Standards
Some differentiate between a coding Style and Standard. Most use the term Standard as a Style.
From http://www.jrtwine.com/Articles/CodingStyles/CStyle1.htm
Most coding standards that I have encountered are little more than coding style documents. What is
the difference? A coding style specifies things like how you indent, tabs vs. spaces, use of "reverseHungarian" notation for naming of variables, etc. A coding standard often includes a coding style,
but goes beyond just how to name a variable: it tells you how that variable should be treated and
when it should (and should not be) used.
im
First, the coding standard-related parts of the code: This is for bullet proof code and may be on the
extreme side of coding. Let’s discuss the below from the above website.
1. Functions should always return a status value indicating success or failure, and additional
information if possible.
a. No void or bool functions unless the action that the function performs is atomic and has
very few reasons for failure.
b. These return codes should always be tested upon return.
2. Avoid manipulating your own resources in utility functions if possible.
a. That way, you reduce the chance of that utility code being responsible for not closing a
particular file, or leaking some memory under certain situations.
3. Negative Buffer sizes do not make sense, so use an unsigned value for them. (this holds for
languages that allow you to directly allocate memory, like C.
a. This applies to other situations, where negative values should not happen, like loop
indices.
4. Use unsigned integers when negative values should not be possible (loop counters for
example).
5. Any function that takes a previously allocated/sized buffer as a parameter must take the
available/usable size of that buffer as well.
a. This can be generalized to arrays. Many languages do not by default check array
bounds, we should have const for upper array bounds checking and variables that define
©2012 Mike Rowe
Page 2
2/8/2016 4:11:00 PM
SE 386 Software Maintenance and Reengineering
Notes 006- Coding Standards
what parts of the array have been used v. unused.
6. All pointers and buffer parameters are to be at least NULL and length checked before use.
a. If you dereference a NULL pointer, you did not follow this simple rule.
7. This is probably not very useful --- All line-by-line comments start at column 61 and code
lines are to be broken before that column whenever possible (quoted strings are an
exception to the "line break" rule).
a. Why write comments like that? Using a piece of paper or your hand, cover the
comments and have a non-technical (non-developer) person try to tell you what the
code is doing. Now, switch and cover the code and/or expose the comments and ask
again. You have very likely just answered your own question!
8. Never hide or mask an operating system generated error unless required. The OS has
many more error messages than your application does, reuse them whenever possible.
9. When taking a buffer for processing, return the length of processed data.
10. And lastly, as the implementation of the swap demonstrates, always favor the KISS
Philosophy over trying to be too fancy!
Second, the coding style-related parts of the code:
1. Variables shall use the "reverse-Hungarian" notation of naming. In this e0xample, "h" for
"HANDLE", "bta" for "BYTE array", "fb" for "Fake Bool or BOOL" and "dw" for DWORD. I
don’t think this is widely used anymore – camel hump is more often used.
2. This is more of a coding standard: Use array notation in parameter lists for buffers of
known or specified size, and pointer notation for buffers of unknown (but deterministic)
size like NULL-terminated character strings.
a. Also, only use pointers when a parameter can be NULL and/or optional.
b. The rationale behind that is that a pointer CAN point to a block of memory (or NULL),
but an array IS a block of memory (even though arrays degrade into pointers). This to
me is approaching standard in that it could impact safety of code.
3. Double-indent continued lines from the indented "point of origin".
4. If statements and loops will always use brackets (compound statement), even for singleline controlled statements, and they will always exist on their own lines at the same indent
level as the controlling statement/loop. Same for functions, classes, structs, etc.
©2012 Mike Rowe
Page 3
2/8/2016 4:11:00 PM
SE 386 Software Maintenance and Reengineering
Notes 006- Coding Standards
5. The coding standard parts are obviously more important. Just about any developer can use
the "LTTLS" (Look To The Left, Stupid) technique to find out what a variable's type is, and
can figure out different indenting and bracketing behavior.
An easy way to tell the difference between parts that are style and parts that are standard is to
compare the functionality of the code if either element was removed or changed.
 For example, if the style points were not followed for the above code, the code would still work
exactly the same way, with exactly the same behavior and safety checks.
 However, if you removed the standard parts of the code, you then reduce the codes "safety"
and functionality.
 That is the difference between the two; standard is obviously more important than style.
1.2 See the CS 143 example that disproves # 5.
1.3 There are many public coding standards





The GNU standards http://www.gnu.org/prep/standards/standards.html
Visual Studio Coding Techniques:
http://msdn.microsoft.com/library/default.asp?url=/library/enus/vsent7/html/vxconcodingtechniques.asp (less than 10 pages)
Java Coding Standard http://geosoft.no/development/javastyle.html (long)
C# Coding Standard http://www.tiobe.com/standards/gemrcsharpcs.pdf
C Coding Standard http://www.psgd.org/paul/docs/cstyle/cstyle.htm
1.4 Is it good to have short or long coding standards?
1.5 What needs to be covered



Layout
o Of system
o Of source file
o Declarations/definitions
Naming
o Classes
o Routines
o Variables
o Constants
o Files
Comments
o Intellectual Rights
 Make sure if you are using other’s code that you need to cite this.
©2012 Mike Rowe
Page 4
2/8/2016 4:11:00 PM
SE 386 Software Maintenance and Reengineering
Notes 006- Coding Standards


 ACM’s brief listing of ethics standards has two points relating to this issue
o Content
o Format
o Files, Classes, Functions, parameters, …
Format of code
o Indentation
o Blocks Structures
o Line Length – how to break long statements
o Statements
o Function length
o Content of a file
Process
o TDD
o Tags for forward and reverse engineering
1.6 Process for adopting a Coding Standard from http://www.tiobe.com/
TIOBE Coding Standard Methodology
TIOBE has developed a step-by-step methodology to support companies to introduce coding standards
into their organization. The methodology consists of 7 logical steps and is based on years of experience
in the field. The independent nature of the steps allows organizations to take a sufficient break after
each step to get familiar with the new situation. The 7 steps are shown in the figure below.
©2012 Mike Rowe
Page 5
2/8/2016 4:11:00 PM
SE 386 Software Maintenance and Reengineering
Notes 006- Coding Standards
1.7 Team Presentation Ideas: Automatic Style checker, see:











Lots of tools, including a C# checker, http://www.tiobe.com/
The lint program to check your C code for errors that may cause a compilation failure or
unexpected results at runtime. In many cases, lint warns you about incorrect, error-prone, or
nonstandard code that the compiler does not necessarily flag.
http://docs.sun.com/source/806-3567/lint.html
Splint is a tool for statically checking C programs for security vulnerabilities and coding
mistakes. With minimal effort, Splint can be used as a better lint. If additional effort is invested
adding annotations to programs, Splint can perform stronger checking than can be done by any
standard lint. http://lclint.cs.virginia.edu/
A PC Lint for C/C++ (also other platforms) http://www.gimpel.com/
An automated C/ C++ source code analysis product that uses over 500 coding guidelines to
automatically identify dangerous coding constructs that compilers do not detect.
http://www.parasoft.com/jsp/products/home.jsp?product=Wizard&itemId=50
FxCop is a code analysis tool that checks .NET managed code assemblies for conformance to the
Microsoft .NET Framework Design Guidelines http://www.gotdotnet.com/team/fxcop/
C# code checker http://www.tiobe.com/index.htm?clocksharp
Checkstyle is a development tool to help programmers write Java code that adheres to a coding
standard. It automates the process of checking Java code to spare humans of this boring (but
important) task. This makes it ideal for projects that want to enforce a coding standard.
http://checkstyle.sourceforge.net/
(JAVA) JCSC is a powerful tool to check source code against a highly definable coding standard
and potential bad code. The standard covers naming conventions for class, interfaces, fields,
parameter, ... . Also the structural layout of the type (class/interface) can be defined.
http://jcsc.sourceforge.net/
Automates Java unit testing & code compliance. Auto-generates JUnit test cases from a running
application. And tests individual classes or large, complex applications.
http://www.parasoft.com/jsp/products/home.jsp?product=Jtest&itemId=11
Numerous web standards.
©2012 Mike Rowe
Page 6
2/8/2016 4:11:00 PM