Coding Standards and Conventions

Diomidis Spinellis
Department of Management Science and Technology
Athens University of Economics and Business
Athens, Greece
dds@aueb.gr

File Names and Organization

Common File Names

File Name Contents
README Project overview
MANIFEST List of project files with brief explanations
INSTALL Installation instructions
Copying Licensing information
TODO Wish list for future extensions
NEWS Documentation on user-visible changes
Changes Code change summary
configure Platform configuration script
Makefile Build specification
Makefile.SH Shell script producing the above
config.h Platform configuration definitions
config_h.SH Shell script producing the above
patchlevel.h Defines the project release version

Common File Extensions

Extention Contents
.man Unix manual page source
.encoding Text in a particular encoding (e.g. .utf8)
.language-code Text in a particular language (e.g. .de for German)
.lib Library---collection of object files
.s Assembly language source (Microsoft DOS / Windows, Unix)
.psp Web server-executed source
.awk Awk (language) source
.frm Microsoft Visual Basic source
.com MS-DOS/NT, OS/2 Rexx , VMS commands
.png Microsoft Windows, X-Windows, portable bitmap file
.c C source
.cpp, .cxx C++ source
.cs C# source
.class Java compiled file
.sh Unix csh, sh (Bourne) shell source
.def Microsoft Windows or OS/2 executable or shared library definition
.so Shared object library (Microsoft Windows, Unix)
.vbp Microsoft Developer Studio project and workspace file
.dvi Documentation in troff or TeX device-independent output
.el Emacs lisp source
.tbl Equations, pictures, tables to be typeset by eqn, pic, tbl
.Z File compressed with gzip or compress
.h C or C++ header file
.hpp C++ header file
.icon Microsoft Windows, X-Windows icon
.idl Interface definition file
.info Documentation generated by GNU Texinfo
.tar File collection in Java, Unix shell, tape archive format
.java Java source code
.jcl IBM JCL instructions
.l Lex (lexical analyzer generator) source
.m4 M4 (macro processor) code
.mk Makefile (also often without any extension)
.mif Documentation exported by FrameMaker
.me Documentation using troff mm, me macros
.roff Documentation in plain troff format
.obj Object file
.ok Local additions to the spell-check dictionary
.pod Perl, module source, documentation
.ps Postscript source, or formatted documentation
.py Python source
.rb Ruby source
.res Microsoft Windows resource, compiled resource script
.sed Sed (stream editor) source
.test Test file
.tcl Tcl/Tk source
.texi Documentation in TeX or LaTeX, GNU Texinfo format
.y Yacc (parser generator) source

Indentation

Formatting

Comments

Comments are not only read by humans:

Naming Convention Styles

Three naming conventions:
  1. Capitalization, or CamelCase. Examples:
  2. Underscore separation (exponent_is_negative) (GNU)
  3. Initials (splbio : set processor level for buffered I/O); also removal of vowels and word endings (strcmp)

Java Naming Conventions

We can thus differentiate between static method calls and message dispatches:

Hungarian Notation

Primitive Types

ConstructMeaning
b Flag (boolean) primitive type
dw Double word (32 bit wide) with arbitrary contents
w Word with arbitrary contents (typically unsigned)
b Byte with arbitrary contents
ch Character
sz Pointer to first character of a null-terminated string
h Handle of a heap-allocated object
fn Function
i Integer
l Long integer (32-bit wide)
n Short integer (16-bit wide)

Type Constructions

ConstructMeaning
pX Pointer to X
dX Difference between two instances of X
cX Count of instances of type X
mpX Y Array (map) of Ys indexed by X
rgX Array (range) of Xs
iX Index to array rg X
cbX Size of instances of X in bytes
cwX Size of instances of X in words

Name Qualifiers

ConstructMeaning
XFirst First element of an ordered set of type X values
XLast Last element of an ordered set of type X values.
XNext Next element of an ordered set of type X values
XPrev Previous element of an ordered set of type X values
XLim The upper limit of a range of X values.
XMac The current upper limit
XNil A special Nil value of type X
XT A temporary value of type X

VB Primitive Types

ConstructMeaning
cur Currency
time Time
date Date
dt Date and time combined
qry Database query
tbl Database table

VB Common Controls

ConstructMeaning
frm Form
mnu Form menu
cmd Command button
chk Check button
opt Radio button
lbl Text label
txt Text edit box
pb Picture box
pic Picture
lst List box
cbo Combo box
tmr Timer

Programming Practices

Established practices help you read standard code patterns, and identify deviations.

Examples:

Process Standards

Further Reading

Exercises and Discussion Topics

  1. Identify the coding standards that apply in your organization. In the form of a table, compare their coverage against two other commonly used standards.
  2. Discuss the advantages and disadvantages of defining and declaring code elements in a strictly prescribed order. How do modern integrated development environments affect your view?
  3. Devise a guideline that prescribes under what circumstances the formatting of an imported piece of code should be changed to conform to the local coding standards. Take into account code quality, readability, maintenance, revision control, and future integration issues.
  4. Some argue that the Hungarian naming conventions duplicate work that is performed by a type checking compiler. Discuss.
  5. Create an itemized list of programming practices that can help code readability. Try, where possible, to reference existing examples.
  6. Identify the process standards that apply in your organization. Explain what software elements (files, directories) have to be examined in order to verify the conformance of a system against those standards.