CSC/ECE 517 Summer 2008/wiki2 2 ar: Difference between revisions
(→Links) |
(→Links) |
||
(5 intermediate revisions by the same user not shown) | |||
Line 169: | Line 169: | ||
=Links= | =Links= | ||
* [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] | |||
* [http://en.wikipedia.org/wiki/CamelCase CamelCase] | |||
* [http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code How to Improve the Readability of your software code] | |||
* [http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076 Program Comprehension During Software Maintenance and Evolution] | |||
* [http://www.perlmonks.org/?node_id=592616 What is code readability?] | |||
* [http://en.wikipedia.org/wiki/Source_code Source Code] | |||
* [http://www.javalobby.org/java/forums/t96280.html Does "code readability" mean different things to different people?] | |||
* [http://en.wikipedia.org/wiki/Naming_convention Naming convention] | |||
* [http://msdn.microsoft.com/en-us/library/ms229045.aspx .NET General Naming Conventions] | |||
==Coding conventions for languages== | ==Coding conventions for languages== | ||
*ActionScript(Flex): [http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions Flex SDK coding conventions and best practices] | *ActionScript(Flex): [http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions Flex SDK coding conventions and best practices] | ||
Line 182: | Line 191: | ||
*PHP::PEAR: [http://pear.php.net/manual/en/standards.php PHP::PEAR Coding Standards] | *PHP::PEAR: [http://pear.php.net/manual/en/standards.php PHP::PEAR Coding Standards] | ||
*Python: [http://www.python.org/peps/pep-0008.html Style Guide for Python Code] | *Python: [http://www.python.org/peps/pep-0008.html Style Guide for Python Code] | ||
*Ruby: [http://itsignals.cascadia.com.au/?p=7 Ruby and Rails Naming Conventions] | |||
==Coding conventions for projects== | ==Coding conventions for projects== | ||
*[http://httpd.apache.org/dev/styleguide.html Apache Developers' C Language Style Guide] | *[http://httpd.apache.org/dev/styleguide.html Apache Developers' C Language Style Guide] | ||
Line 188: | Line 198: | ||
*[ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/src/share/misc/style The NetBSD source code style guide (formerly known as the BSD Kernel Normal Form)] | *[ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-current/src/share/misc/style The NetBSD source code style guide (formerly known as the BSD Kernel Normal Form)] | ||
==CheckStyle== | ==CheckStyle== | ||
[http://checkstyle.sourceforge.net/ CheckStyle project website] | *[http://checkstyle.sourceforge.net/ CheckStyle project website] | ||
[http://blogs.sun.com/geertjan/entry/checkstyle CheckStyle with Netbeans] | *[http://blogs.sun.com/geertjan/entry/checkstyle CheckStyle with Netbeans] | ||
[http://www.testearly.com/2007/06/06/agile-developers-toolbox-checkstyle-for-eclipse/ CheckStyle with Eclipse] | *[http://www.testearly.com/2007/06/06/agile-developers-toolbox-checkstyle-for-eclipse/ CheckStyle with Eclipse] | ||
[http://eclipse-cs.sourceforge.net/ Checkstyle plugin for Eclipse] | *[http://eclipse-cs.sourceforge.net/ Checkstyle plugin for Eclipse] | ||
[http://javaboutique.internet.com/reviews/checkstyle/ Good tutorial with some background] | *[http://javaboutique.internet.com/reviews/checkstyle/ Good tutorial with some background] |
Latest revision as of 18:38, 25 June 2008
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
- Organization of code - Organization of code is a difficult job. As amount and complexity increases it become harder to do that.
- 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.
- 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)