CSC/ECE 517 Summer 2008/wiki2 2 ar

Introduction

This wiki entry will discusses about the importance of naming conventions and how they effect the readability of source code? It also shows examples of Java and Ruby langauge naming conventions.

Background

Source code

The source code is a set of computer instructions written mostly in ASCII text following some specific high level computer language syntaxes. They are human readable and need some special programs (Compilers and Interpreters) to convert it into machine languages. They actually represent the logic of the program.

Problems face by source code

1. Organization of code - Organization of code is a difficult job. As amount and complexity increases it become harder to do that.
2. Source code comprehension - Source code readability is actually associated with source code comprehension. It is foundation through which a developer make sense of source code. There are some other techniques/tools available that support program comprehension but nothing could match with batter readable source code.
3. Complex computer language syntaxes - Some time computer languages design with complex notations, that make those languages very powerful but it also forces programmer to stop first to understand the language constructs then follow the actual program logic.

Naming conventions

Naming conventions is standard way of making names of things to embed additional information. This technique is very effectively used in normal life to remove irregularities. Numbering houses even and odd numbers across street to represent there direction on the road is an example of simple naming conventions.

In computer languages naming convention mostly represent rules for defining different identifiers in the program. Class names, variable names, and source file names are good examples of such rules. Good naming rules increase the source code comprehension. In some modern languages (Ruby and Ruby-on-Rails) these convention even also used as configuration information.

Benefits of standardize naming conventions

• Improve source code comprehension.
• Reduces the maintenance cost.
• Could be used as configuration information.
• Improves code readability.
• Could allow to embed metadata information with identifier names.
• Avoids the "naming collisions".
• Reduces the requirement of program documentation

Factors effecting naming conventions

Language specific

Readability of source code is very specific to target language. When developers move from one language to other, they start complaining about existing coding standards but later they would figure out the reason for those standards. Joel Spolky has a nice article (Making Wrong Code Look Wrong) addressing this issue.

Nature of work/domain

Nature of software is also very important factor effecting naming conventions. A developer who never worked on web application development might complain about lack of comments explaining session and cookies variables but for web application developer it is common thing.

Developers preferences

Developers are people and as every person has different taste for clothing and food, similarly developers have opinion about different style of naming. Some developers who are coming from embedded or real-time software development might like smaller names then developers of business applications.

Elements of naming conventions

There are number of elements that define the basics of naming conventions. They actually differentiate one naming standard from another one. These elements are influence by the factors we discussed in last section.

Length of identifiers

This element is part of big debate both in professional and academic circles, what is good, brevity or expressiveness? Some standards recommend fixed size names, some don’t allow abbreviations, some ask to add specific characters to define the type of identifier (like use of I to represent interface classes etc.).

Letter case and numerals

Some conventions have rules about case of letters according to there types (Like first Uppercase letter for class names and first lowercase letter for method names) and some use no restriction on letters case but add numbers or special characters to identifies the type of identifiers (Like in ruby @ use for public variables etc.)

Word boundaries

For multiple words most of languages do not allow whitespaces in identifier names. Some recommend using underscore (“_”) character as separator or use of CamelCase. CamelCase technique uses uppercase letter to define the word boundaries. For example,

EmployeeType

addOrder	

CamelCase works most of time but with acronym it procedures bad names like DaoEmploye.

General naming conventions

There are few naming conventions that are not specific to any language but include the basic principles of program languages. In these conventions naming of identifies not only reflects the domain but also platform specific types too.

Hungarian notations

This is a well-known naming convention that incorporates purpose or type of identity with its name. Examples,

IEmployeeType // Interface name

btnSubmit // Submit Button 

arrEmployees // employees array

strUsername // user name in string

Positional notations

This convention mostly used in mainframe and COBOL environment where system usually has limitation on numbers of character use for identifier names. A typical scheme is something like, two characters for application name, three characters for module or process name in that application and rest is numbers to make them unique.

OPCAT001 // OP - Order processing, CAT - Catalog, 001 - first variable

Language specific naming conventions

Java

Sun has a very comprehensive guideline for Java source coding. It includes everything from source code organization to naming classes. It is difficult to include everything here. I am going to just specify the naming convention for basic things,

Packages

Prefix of package names is always in all lowercase. It is also recommended to start the package names from top-level domain names i.e., com, edu, org, mil, net. Examples,

com.sun.lang, edu.ncsu.csc517.pg

Classes

Class names should be nouns and starting character should be capital. If name requires any division, then use mixed case where every starting character is capital. Examples,

class Employee

class GraduateStudent.

Interfaces

Names for interfaces should also follow the class name conventions. Examples,

interface DataAccessObject

interface StudyType.

Method Names

Method names should start with some verb and first letter is in lowercase. Examples,

runApp()

addCustomerOrderInformation

Variables

Variable names also follow method naming rules. Examples,

studentId

employeeName

Constants

Class constants and ANSI standard constant should be all upper case separated by underscores (“_”). Examples,

EMPLOYEE_MAX_AGE

WINDOW_WIDTH

Ruby

Most of the time, Ruby and Ruby-on-Rails follow the same naming convention like Java. But there are a few differences. One more thing we should be careful about Ruby and Ruby-on-Rails is, since they follow convention over configuration schema, some naming rules are more important for successful execution of application.

Local variables

All lowercase letters are separated by underscores. Examples:

employee_age

If it is starts with a capital letter then it is a constant. Example

Constant=10

Instance variables

Starts with single “at” sign (@) follow by name. It is suggested to have all lowercase for variable name after @ sign. Examples,

@name

@address

Instance Method

Starts with lowercase letter follow by digits, underscores and letters. Examples,

paint_door

manager?.

Class variables

Starts with double “at” signs (@@) and followed by letters, digits, and underscores. Examples,

@@employee

Constants

Starts with an upper case letter followed by other characters. Sometimes, developers use all upper case names for constant. Examples,

PI

MAX_AGE.

Class and Modules

Class and module names start with uppercase. Examples,

Class Employee

module DatabaseFunctions.

Global variables

Starts with dollar ($) sign and followed by characters. Examples,

$company

Tools

Developing naming conventions is a smaller job then actually making sure those rules are being followed by the team. Luckily there are few tools available that make this task easier. I have used CheckStyle on my job and it worked beautifully. Checkstyle is a fully configurable development tool that makes sure that code is following proper naming conventions. It has integration available with all well known development environments. I have included few links to tutorials using checkstyle in Eclipse and Netbeans in links section.

Conclusion

Cost of software development keeps increasing and especially maintenance cost is hurting lot of in-production applications. Major contributor to high cost is associated with difficulty to understand the existing code. A lot of time documentation is not synchronized with code updates. In those cases the importance of code readability increases even more. Having proper naming conventions not only improves the development time but it also reduces the cost of maintenance.

Establishing naming convention is very tricky area. It should not be develop in isolation. Team’s developers’ suggestion should also consider besides looking at industry standards. All successful open source projects start with proper naming conventions. I have included few links, in case someone need some examples.

Links

• Hungarian notation
• CamelCase
• How to Improve the Readability of your software code
• Program Comprehension During Software Maintenance and Evolution
• What is code readability?
• Source Code
• Does "code readability" mean different things to different people?
• Naming convention
• .NET General Naming Conventions

Coding conventions for languages

• ActionScript(Flex): Flex SDK coding conventions and best practices
• C++: C++ Programming/Code Style
• C++: GeoSoft's C++ Programming Style Guidelines
• C#: Coding Standard: C# (Philips Medical Systems)
• D: The D Style
• Erlang: Erlang Programming Rules and Conventions
• Java: Sun official Java coding style
• Lisp: Riastradh's Lisp Style Rules
• Mono: Programming style for Mono
• Perl: Perl Style Guide
• PHP::PEAR: PHP::PEAR Coding Standards
• Python: Style Guide for Python Code
• Ruby: Ruby and Rails Naming Conventions

Coding conventions for projects

• Apache Developers' C Language Style Guide
• Linux Kernel Coding Style
• Mozilla Coding Style Guide
• The NetBSD source code style guide (formerly known as the BSD Kernel Normal Form)

CheckStyle

• CheckStyle project website
• CheckStyle with Netbeans
• CheckStyle with Eclipse
• Checkstyle plugin for Eclipse
• Good tutorial with some background