CSC/ECE 517 Summer 2008/wiki2 2 ar

Introduction

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.

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

Links

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