Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:11:56Z

Bazinga: /* Hungarian Notation: */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

[http://en.wikipedia.org/wiki/CamelCase/ Camel case] is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

[http://en.wikipedia.org/wiki/Hungarian_notation/ Hungarian Notation] is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:11:48Z

Bazinga: /* Hungarian Notation: */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

[http://en.wikipedia.org/wiki/CamelCase/ Camel case] is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

[http://en.wikipedia.org/wiki/Hungarian_notation / Hungarian Notation] is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:11:29Z

Bazinga: /* Hungarian Notation: */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

[http://en.wikipedia.org/wiki/CamelCase/ Camel case] is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

[ http://en.wikipedia.org/wiki/Hungarian_notation \ Hungarian Notation] is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:11:15Z

Bazinga: /* Hungarian Notation: */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

[http://en.wikipedia.org/wiki/CamelCase/ Camel case] is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

[ http://en.wikipedia.org/wiki/Hungarian_notation/ Hungarian Notation] is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:11:03Z

Bazinga: /* Hungarian Notation: */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

[http://en.wikipedia.org/wiki/CamelCase/ Camel case] is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

[ http://en.wikipedia.org/wiki/Hungarian_notation/Hungarian Notation] is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:10:25Z

Bazinga: /* camelCasing and CamelCasing: */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

[http://en.wikipedia.org/wiki/CamelCase/ Camel case] is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:09:37Z

Bazinga: /* camelCasing and CamelCasing: */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

Camel case [[#2foot|[1]]] is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:07:32Z

Bazinga: /* camelCasing and CamelCasing: */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

Camel case [[#1foot|[1]]] is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:06:38Z

Bazinga: /* Introduction */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/ Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

Camel case is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T02:06:12Z

Bazinga: /* Introduction */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
[http://en.wikipedia.org/wiki/Naming_conventions_(programming)/Naming conventions] is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

Camel case is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled, Comparable

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T01:33:45Z

Bazinga: /* Introduction */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
Naming conventions is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

Camel case is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled.

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T01:33:08Z

Bazinga:

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
Naming conventions is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

Camel case is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled.

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links(Language specific Conventions)==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

==Other useful links on naming conventions==
<ul>
<li>Hungarian notation[http://en.wikipedia.org/wiki/Hungarian_notation]</li>
<li>CamelCase[http://en.wikipedia.org/wiki/CamelCase]</li>
<li>How to Improve the Readability of your software code[http://www.wikihow.com/Improve-the-Readability-of-Your-Software-Code]</li>
<li>Program Comprehension During Software Maintenance and Evolution[http://csdl2.computer.org/persagen/DLAbsToc.jsp?resourcePath=/dl/mags/co/&toc=comp/mags/co/1995/08/r8toc.xml&DOI=10.1109/2.402076]</li>
<li>What is code readability?[http://www.perlmonks.org/?node_id=592616]</li>
<li>Variable and Function Naming Convention[http://faculty.ed.umuc.edu/~jrugg/policy/vrbl_naming_convention.htm] </li>

</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T01:29:59Z

Bazinga:

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
Naming conventions is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

Camel case is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled.

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills. 

==Links: ==
(As our topic wasn’t specific to any language related conventions, if any further help is required one can see the following link to look for specific naming styles)
<ul>
Language specific conventions:
<li>C++: GeoSoft's C++ Programming Style Guidelines[http://geosoft.no/development/cppstyle.html]</li>
<li>C#: Coding Standard: C# (Philips Medical Systems)[http://www.tiobe.com/standards/gemrcsharpcs.pdf]</li>
<li>D: The D Style[http://www.digitalmars.com/d/1.0/dstyle.html]</li>
<li>Erlang: Erlang Programming Rules and Conventions[http://www.erlang.se/doc/programming_rules.shtml]</li>
<li>Java: Sun official Java coding style[http://java.sun.com/docs/codeconv/]</li>
<li>Lisp: Riastradh's Lisp Style Rules[http://mumble.net/~campbell/scheme/style.txt]</li>
<li>Mono: Programming style for Mono[http://www.mono-project.com/Coding_Guidelines]</li>
<li>Perl: Perl Style Guide[http://perldoc.perl.org/perlstyle.html]</li>
<li>PHP::PEAR: PHP::PEAR Coding Standards[http://pear.php.net/manual/en/standards.php]</li>
<li>Python: Style Guide for Python Code[http://www.python.org/peps/pep-0008.html]</li>
<li>Ruby: Ruby and Rails Naming Conventions[http://itsignals.cascadia.com.au/?p=7]</li>
<li>ActionScript(Flex): Flex SDK coding conventions and best practices[http://opensource.adobe.com/wiki/display/flexsdk/Coding+Conventions]</li>
</ul>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T01:24:32Z

Bazinga: /* Introduction */

Variable Naming Conventions 

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
Naming conventions is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

In this tutorial, we look at some rules and guidelines to pick good variable names.

==Guidelines to choose good variable names==

===Length of variables:===

This is the most fundamental element of all naming conventions. Some conventions give a fixed number of characters to be used and some are heuristics.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
When choosing length of the name we have to be careful that they are not so short that they cannot be identified uniquely by search and replace tools and not so long that it looks cluttered. The name should be short enough to look neat and also long enough to encode enough information about its use and be found easily.
Example: suppose you were to declare an array to contain id’s of all students in class, you can have a variable name int IdsOfStudentsInClass[]. You need not have such a long name unless it is absolutely essential. You can instead have a name such as int StudentIds[]. This provides enough information about what the variable is used for and is short enough that it does not make the code look bad.

The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). (ANSI constants should be avoided, for ease of debugging.)

===Using Multiple-words in a variable:===

Using multiple words in a variable might be helpful in some cases because one word might not describe its use entirely and clearly. However, if we use multiple words in a variable name, we need a way to delimit the two words.

Two ways are usually used to delimit multiple words: one way is to delimit them using an underscore or dash, or some other non alphanumeric character which looks readable.

Underscores are usually not used within names in object oriented languages as they are used to separate module prefixes from identifiers.

Forbidden: Read_Master_Data() 
Allowed: ReadMasterData() 
Accnt_ReadMasterData() 

If a variable is a constant throughout the code, one should use all upper case letters in order to name it. Underscore can even be used for good readability. 

For example, MAX_WIDTH, RADIUS_EARTH etc.

Another way of doing the same is by using capitalization where we capitalize the first letters of every word or capitalize the first letter of every new word apart from the first word. This is usually called camel casing.

===camelCasing and CamelCasing:===

Camel case is the use of capitalization to add clarity to compound names assigned in code. It evolved as a common standard because of the need to avoid commonly available delimiters, such as hyphens (-) or underscores (_), that were used as keywords in the syntax of languages. There are two common variants of camel case that are used.

Lower camel case (or camelCase) involves using a lower-case letter for the first word in the name with each subsequent word using an upper-case letter.

int setVariable(){
}

Upper camel case (or CamelCase) involves using an upper-case letter for the first word in the name and for all subsequent words. CamelCase is sometimes referred to as PascalCase.

int SetVariable(){
}

This convention can be used for variable names as well. camelCase or CamelCase is often times used as the foundation for language-specific naming conventions.

===Prefixing:===
It can be useful to use prefixes for certain types of data to remind you what they are: for instance, if you have a pointer, prefixing it with "p_" tells you that it's a pointer. If you see an assignment between a variable starting with "p_" and one that doesn't begin with "p_", then you immediately know that something fishy is going on. It can also be useful to use a prefix for global or static variables because each of these has a different behavior than a normal local variable. In the case of global variables, it is especially useful to use a prefix in order to prevent naming collisions with local variables (which can lead to confusion). For example, g can be used as prefix for any global variable. L can he used for local scope. When we want to represent data types we can use i for Integers f for Float (double or single) and so on.

Example: if you have an integer pointer, you can declare it as int p_studentIds; suppose this was a global variable, you could have it as
int gp_studentIds. The prefix gp clearly shows that this is a global pointer. This also avoids collision with the local variable
p_studentIds incase you wanted to have them both.

A common convention is to prefix the private fields and methods of a class with an underscore: e.g., _private_data. This can make it easier to find out where to look in the body of a class for the declaration of a method, and it also helps keep straight what you should and should not do with a variable. For instance, a common rule is to avoid returning non-const references to fields of a class from functions that are more public than the field. For instance, if _age is a private field, then the public getAge function probably shouldn't return a non-const reference since doing so effectively grants write access to the field!

===Using Parts of Speech:===
Parts of speech can be used extensively while defining the variable names, be it class-name, variable-name or method-name. Following are the standard form to use:

<ol>
<li>Singular noun to describe class, interface, record, variable, field, accessor method, exception.</li>
For example: JButton, JWindow.
<li>Plural noun to describe a variable or field holding a collection.</li>
For example: Items, Classes.
<li>Verbs to describe methods. </li>
For example: dispose, getItems, delete.
<li>Adjectives to describe interface and boolean.</li>
For example: cloneable, IsEnabled.

</ol>
Avoid using reserved word or a keyword related to any language as this can lead to ambiguity.

===Abbreviations:===

Abbreviations are dangerous--vowels are useful and can speed up code reading. Resorting to abbreviations can be useful when the name itself is extremely long because names that are too long can be as hard to read as names that are too short. When possible, be consistent about using particular abbreviations, and restrict yourself to using only a small number of them. 

Common abbreviations include "itr" for "iterator" or "ptr" for pointer. Even names like i, j, and k are perfectly fine for loop counter variables (primarily because they are so common). Bad abbreviations include things like cmptRngFrmRng, which at the savings of only a few letters eliminates a great deal of readability. If you don't like typing long names, look into the auto-complete facilities of your text editor. You should rarely need to type out a full identifier. (In fact, you rarely want to do this: typos can be incredibly hard to spot.)

 The above were guidelines to pick good variable names. These are not rules as such but following them will help in writing good and readable programs. However, the most important thing to follow is to be consistent. When we choose a particular guideline, we should make sure we follow it all through the program. One of the disadvantages about using naming conventions is that naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being used or returned.

===Hungarian Notation:===

Hungarian Notation is a language independent identifier naming convention used in computer programming. The notation indicates explicitly the intended use or the type of the variable or function which is named. The variable name starts with a single letter or a group of letters also called as mnemonics, which is then followed by the intended variable name desired by the programmer. Here we can even use the Camel Case convention like capitalizing first letter to distinguish the variable from type indicating variables.

Following examples will cement the use of Hungarian Notation
1. bCondition : Boolean
2. fCondition : boolean (flag)
3. chState : charr
4. cItems : count of items
5. dwLightYears : double word
6. nItem : integer or count
7. iSize : integer or index
8. fpCost: floating-point
9. dbPi : double
10. pMemory : pointer
11. rgMonth : array, or range
12. szLastName : zero-terminated string
13. u16Identifier : unsigned 16-bit integer
14. stClassroom : clock time structure
15. fnFunction : function name

The scope of a variable can even be described by choosing following convention. This extension is often also used without the Hungarian type-specification,

1. g_nColour : member of a global namespace, integer
2. m_nColour : member of a structure/class, integer
3. m_colours : member of a structure/class
4. s_colours: static member of a class
5. _colours : local variable

The various advantages of using Hungarian type notation are: the name denotes the type of variable, we can have many variable of same name but different datatypes like illength(integer) ,dwlength(double word) etc. However, there are some disadvantages of this notation as it can make the code look ugly. Also we can’t use editor completion support feature in writing a code.

==Conclusion:==

Most of software projects today are developed as open source, and more over they are developed with the participation of various teams working on different parts of the project. So the most important part of the code is readability in other words using proper naming conventions throughout the project. The advantages of using naming conventions outweigh its disadvantages. If proper conventions aren’t used, the overall cost of software development can increase multifold. Proper documentation of the convention used can save a lot of time and cost later. Even the maintainability of the code is highly achieved. One should use any of the above described naming conventions in order to develop healthy software development skills.

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T01:00:00Z

Bazinga:

<h1>Variable Naming Conventions</h1>

Almost all programming languages allow the programmer a great deal of freedom when naming variables in a program's source code. But choosing good names is hard. This is a tutorial on how to choose good variable names! 

==Introduction==
Naming conventions is one topic in programming that has probably not been emphasized enough. There has always been a debate about its importance and effort taken to learn and follow them. Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code thereby reducing development time specially when the code is large.

As an example, say a variable holds the average age of students in a class. Int averageAge or int AverageAge gives a lot of information to the programmer about what the variable does than say just int a; Also capitalizing the very first letter of every word makes it more readable than just int averageage.

In this chapter, we are mainly going to look at some rules and guidelines to choose good variable names.


==Advantages of using naming conventions==
<ol>
<li>Having good names provides additional information (metadata) to programmers about what the variables are used for. As in the example above, a good name goes a long way in giving out specific use of variable which makes code more readable.</li>
<li>Having a convention or standard helps in having a consistent look to the code. When the development team is large and various people are working on various parts of a project, looking at some other section of the code should not look very different from what someone has written themselves.</li>
<li>Conventions usually will have rules or guidelines to sort out naming of variables or other structures in code to avoid potential ambiguity.</li>
<li>When we use naming conventions, we are forced to use meaningful and professional names rather than cute or funny names. Having good names gives good appearance to the program.</li>
<li>In the case of code reuse after a long interval of time, having a well defined naming convention can help provide better understanding of code.</li>
<li>Well-chosen names make it significantly easier for subsequent generations of analysts and developers to understand what the system is doing and how to fix or extend the source code for new business needs.</li>

</ol>

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T00:54:20Z

Bazinga:

CSC/ECE 517 Fall 2010/ch5 5b RR

2010-11-04T00:50:38Z

Bazinga:

<h1>Variable Naming Conventions</h1>

CSC/ECE 517 Fall 2010/ch1 S10 ms

2010-11-04T00:47:28Z

Bazinga:

*[[CSC/ECE 517 Fall 2010/ch1 1a vc]]

*[[CSC/ECE 517 Fall 2010/ch1 1a br]]

*[[CSC/ECE 517 Fall 2010/ch1 1b mg]]

*[[CSC/ECE 517 Fall 2010/ch1 1c JF]]

*[[CSC/ECE 517 Fall 2010/ch1 1e az]]

*[[CSC/ECE 517 Fall 2010/ch1 1e bb]]

*[[CSC/ECE 517 Fall 2010/ch1 1f vn]]

*[[CSC/ECE 517 Fall 2010/ch1 25 ag]]

*[[CSC/ECE 517 Fall 2010/ch2 2b dg]]

*[[CSC/ECE 517 Fall 2010/ch1 2e RI]]

*[[CSC/ECE 517 Fall 2010/ch1 S6 aa]]

*[[CSC/ECE 517 Fall 2010/ch1 S6 km]]

*[[CSC/ECE 517 Fall 2010/ch1 S10 GP]]

*[[CSC/ECE 517 Fall 2010/ch1 S10 MS]]

*[[CSC/ECE 517 Fall 2010/ch1 S10 MM]]

*[[CSC/ECE 517 Fall 2010/ch1 S10 PH]]

*[[CSC/ECE 517 Fall 2010/ch2 2a CB]]

*[[CSC/ECE 517 Fall 2010/ch2 2a mw]]

*[[CSC/ECE 517 Fall 2010/ch2 2c ck]]

*[[CSC/ECE 517 Fall 2010/ch2 S23 GP]]

*[[CSC/ECE 517 Fall 2010/ch2 S24 NS]]

*[[CSC/ECE 517 Fall 2010/ch2 S23 SS]]

*[[CSC/ECE 517 Fall 2010/ch2 S23 NR]]

*[[CSC/ECE 517 Fall 2010/ch2 S20 TT]]

*[[CSC/ECE 517 Fall 2010/ch2 2d AS]]

*[[CSC/ECE 517 Fall 2010/ch2 S24 rm]]

*[[CSC/ECE 517 Fall 2010/ch3 3a SN]]

*[[CSC/ECE 517 Fall 2010/ch3 3b ka]]

*[[CSC/ECE 517 Fall 2010/ch3 3e br]]

*[[CSC/ECE 517 Fall 2010/ch3 3f lj]]

*[[CSC/ECE 517 Fall 2010/ch3 3h az]]

*[[CSC/ECE 517 Fall 2010/ch3 3h PW]]

*[[CSC/ECE 517 Fall 2010/ch3 3i IC]]

*[[CSC/ECE 517 Fall 2010/ch3 3i MM]]

*[[CSC/ECE 517 Fall 2010/ch3 3j KS]]

*[[CSC/ECE 517 Fall 2010/ch3 S30 SK]]

*[[CSC/ECE 517 Fall 2010/ch3 4b mt]]

*[[CSC/ECE 517 Fall 2010/ch4 4c rn]]

*[[CSC/ECE 517 Fall 2010/ch4 4e ms]]

*[[CSC/ECE 517 Fall 2010/ch4 4f sv]]

*[[CSC/ECE 517 Fall 2010/ch4 4g HW]]

*[[CSC/ECE 517 Fall 2010/ch4 4g km]]

*[[CSC/ECE 517 Fall 2010/ch4 4h am]]

*[[CSC/ECE 517 Fall 2010/ch5 5b mt]]

*[[CSC/ECE 517 Fall 2010/ch5 5b jz]]

*[[CSC/ECE 517 Fall 2010/ch5 5c ck]]

*[[CSC/ECE 517 Fall 2010/ch5 5f SN]]

*[[CSC/ECE 517 Fall 2010/ch5 5a KR]]

*[[CSC/ECE 517 Fall 2010/ch5 5b RR]]

CSC/ECE 517 Fall 2010/ch4 4a RJ

2010-10-20T04:25:33Z

Bazinga: /* Advanced Topics */

Use Cases 
== Introduction ==
== Use Case Basics ==

Use cases can be defined in many ways. There are many formal definitions for it. Very simply put, a use case is a reason to use a system. For example, a student borrowing a book from a library would be a use case of the library or a bank cardholder might need to use an ATM to get cash out of their account. More formally, “a use case is a collection of possible sequences of interactions between the system under discussion and its Users (or Actors), relating to a particular goal” [http://alistair.cockburn.us/Use+case+fundamentals].

A use case is initiated by a user with a particular goal in mind, and completes successfully when that goal is satisfied. The system is treated as a "black box", and the interactions with system, including system responses, are as perceived from outside the system.

Use cases capture who (actor) does what (interaction) with the system, for what purpose (goal), without dealing with system internals. A complete set of use cases specifies all the different ways to use the system, and therefore defines all behavior required of the system, bounding the scope of the system.[http://www.bredemeyer.com/use_cases.htm]

===Terms used with Use cases===
Now let us define some terms used with use cases: [http://en.wikipedia.org/wiki/Use_case]
<ol>
<li>Actor: An actor is a type of user that interacts with the system (ex student borrowing book or cardholder using ATM). Actors are also external entities (people or other systems) who interact with the system to achieve a desired goal. The goal must be of value to the actor.</li>

<li>Goal: Without a goal a use case is useless. There is no need for a use case when there is no need for any actor to achieve a goal. A goal briefly describes what the user intends to achieve with this use case. For example, the goal of a student using the library is to obtain the book. There is no point in having a use case like “the student enters the library” as that in itself has no value to the actor.</li>

<li>Stakeholder: A stakeholder is an individual or department that is affected by the outcome of the use case. Individuals are usually agents of the organization or department for which the use case is being created. A stakeholder might be called on to provide input, feedback, or authorization for the use case. The stakeholder section of the use case can include a brief description of which of these functions the stakeholder is assigned to fulfill.</li>
<li>Trigger: A trigger describes the event that causes the use case to be initiated. This event can be external or internal. If the trigger is not a simple true "event" (e.g., the customer presses a button), but instead "when a set of conditions are met", there will need to be a triggering process that continually (or periodically) runs to test whether the "trigger conditions" are met: the "triggering event" is a signal from the trigger process that the conditions are now met.
In our example with the student, a trigger would be the need for the book due to an approaching exam or test which causes the student to go to the library to borrow a book.
</li>

<li>Precondition: A precondition defines all the conditions that must be true (i.e., describes the state of the system) for the trigger to meaningfully cause the initiation of the use case. That is, if the system is not in the state described in the preconditions, the behavior of the use case is indeterminate. For example, the student should be a member of the library and have the required identity to borrow a book. If the student is not a member of the library, there is no point in the student trying to borrow a book from that library.</li>

<li>Scenarios: A scenario usually specifies when the use case starts and ends. It describes the interaction with actors and shows the flow of events between a user and system. For example, when a student tries to borrow a particular book from the library, it doesn’t always necessarily turn out the same way. Sometimes the book is available and sometimes it is already borrowed by someone else or the library may not have a given book. These are all examples of use case scenarios. The outcome in each case if different depending on circumstances, but they all relate to the same goal that is, they are all triggered by the same need(in this case, need for the book) and all the scenarios have the same starting point.</li>
</ol>

===Simple Example===
Now that we know something about use cases, let us go ahead and describe a simple use case:
Use Case 1: Request book from the library (automated system).

1.1: Summary/Goal
To borrow book a particular book from the library
1.2: Actors
Student
1.3: Preconditions
Student should be a member of the library and have an id.
1.4: Main Path
System requests for student ID and checks if he/she is a member
Student selects “request book”
Student enters name(s) of the book(s)
System checks for availability of books and displays results accordingly
Student confirms the order
System displays details of where the requested books are stacked
1.5: Alternate Path
System does not recognize Id or student is not a member. System will not allow any books to be checked out.
All books requested are already checked out. Displays this information to student and closes request.

===Important Characteristics of Use Cases===
The above description shows a very simple use case. However, there are a few essential characteristics to be noticed about the use case:
<ol>
<li>We have identified the key components of a use case, that is, the goal, actors, preconditions, key scenarios/flow and preconditions. It is very essential that we identify these components before writing a use case.</li>
<li>We have not gone into any sort of technical details about implementation or user interface design. Use cases only represent a very high level design. We are only trying to understand the flow and uses of the system.</li>
<li>We have recorded a set of paths (scenarios) that traverse an actor from a trigger event (start of the use case) to the goal (success scenarios).</li>
<li>We have recorded a set of scenarios that traverse an actor from a trigger event toward a goal but fall short of the goal (failure scenarios).</li>
</ol>

===Where can we use ‘use cases’?===

<ol>
<li>Use cases are usually used to capture the requirements of an interaction based system. When there is a lot of interaction between actors and the system, it makes sense to capture as many interactions and scenarios possible before starting development of the system.</li>
<li>Use cases help to eliminate rework due to requirements misunderstandings between developers and stakeholders by aiming to reach a point where there are no surprises for the users. Use cases help to build an explicit shared understanding that everyone can take away with them, the users, developers, testers, technical authors, and others.</li>
<li>Use cases have received some interest as a starting point for test design. By analyzing use cases for the system, we can know various interactions between the system and actors which will help in drawing out test plans.</li>
</ol>
===Where can’t we use ‘use cases’?===
[ http://en.wikipedia.org/wiki/Use_case]

<ol>
<li>Use case flows are not well suited to easily capturing non-interaction based requirements of a system (such as algorithm or mathematical requirements) or non-functional requirements (such as platform, performance, timing, or safety-critical aspects). These are better specified declaratively elsewhere.</li>
<li>Some systems are better described in an information/data-driven approach than in a functionality-driven approach of use cases. A good example of this kind of system is data-mining systems used for Business Intelligence. If you were to describe this kind of system in a use case model, it would be quite small and uninteresting (there are not many different functions here) but the set of data that the system handles may nevertheless be large and rich in details.</li>
</ol>

===Common mistakes while writing Use cases: ===

<ol>
<li>The system boundary is undefined or inconstant. A system boundary is a boundary that separates the internal components of a system from external entities. If we are not able to identify the system boundaries, we will not be able to clearly define the actors, scenarios and other essential factors involved in writing a good and useful use case. For example, the system described in the library example, has a clear boundary. It is used to accept inputs as book names, checks the id and provides a location for the books. We know its role very clearly. Suppose the system was used to manage everything like security, employee details etc, we will not be able to identify the goal, actors and scenarios very clearly.</li>
<li>Use cases should not be used to capture all the details of a system. The granularity to which you define use cases in a diagram should be enough to keep the use case diagram uncluttered and readable, yet, be complete without missing significant aspects of the required functionality.</li>
<li>The use cases are written from the system’s (not the actors’) point of view. Use cases written from a system point of view will make the writer have the tendency to get into technical details. If we wrote the example test case above from the systems point of view, we would have statements like “obtain location of book from database and display location of books to user”. This is more detail than necessary. Also, this would not capture the interaction with the actor very clearly. Use cases also give a brief insight into how the UI should look but when written from the system these details might not be captured clearly.</li>
</ol>

== Writing Use Cases ==
Writing Use Cases for a system is a process taken between those designing the system and the Stakeholders. There are many different ways to write Use Cases [SOURCE]. Because of this, there are many different formats that Use Cases can take when they are written. There are, however, certain guidelines that should be followed in the process of writing Use Cases. In general, these guidelines are:
<ol>
<li>Never include implementation specific terminology in the Use Case [SOURCE]</li>
<li>Each Use Case should be a set of scenarios, which include different flows of events [SOURCE]</li>
</ol>
=== Iterative Process ===
Normally, this process is done iteratively, so that the iterations can build upon each other [SOURCE]. Below is an example of three iterations of the Use Case writing process to illustrate how it can reveal things about a system and layout the functional requirements. 

For this example, we will be creating Use Cases to solve the following problem statement:

Develop a system to allow users to schedule meetings with each other.

In this system, the stakeholders will be the users of the system. The Users will also be the only Actors in the system. 

==== Iteration 1 ====
For the first iteration, we will write out short sentences to describe the functionality that the system will have. Some use cases could be:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>1</td>
<td>Request a Meeting</td>
<td>User</td>
</tr>
<tr>
<td>2</td>
<td>Approve a meeting request</td>
<td>User</td>
</tr>
<tr>
<td>3</td>
<td>Suggest a new time</td>
<td>User</td>
</tr>
<tr>
<td>4</td>
<td>View a User's schedule</td>
<td>User</td>
</tr>
</table>

In this example, the fourth Use Case may not have been an obvious requirement that could be derived from the original problem statement, but in the process of creating the Use Cases, it was discovered that it would be a good requirement for the system to have.

==== Iteration 2 ====

The next iteration would involve writing out longer descriptions for each. This could be done in paragraph form, or by writing a list. Below are the Use Cases in paragraph form:

'''Use Case 1 – Request a meeting'''
User A chooses the date and time for a meeting with User B. User A chooses User B as the recipient of the meeting request.
User A sends the meeting request to User B through the system. 
'''Use Case 2 – Approve a Meeting Request'''
User A receives a meeting request from User B and accepts the user request. A notification that User A has accepted the meeting is sent to User B. 
'''Use Case 3 – Suggest a different meeting time'''
User A receives a meeting request from User B and suggests a different time and/or date for the meeting. The response is sent to User B through
the system. 
'''Use Case 4 – View a User's schedule'''
User A would like to schedule a meeting with User B. User A starts the system and opens up User B's schedule.
User A can see when User B has already scheduled meetings and User A can then use that information to send User B a meeting request.
Use A can also access their own schedule to view when User A has scheduled meetings. 

From writing out the Use Cases with more description, it should become clear that Use Case 2 and Use Case 3 are very similar. In both Use Cases, User A responds to a meeting request and a response/notification is sent to User B. This might lead the designers of the system to combine these two Use Cases into one Use Case for "Respond to Request."

==== Iteration 3 ====

In the next iteration, we're going to use a Use Case template. There are many different Use Case templates, which include different information [SOURCES]. A template can be created that is unique for the system being described, provided each Use Case uses the same template. The template we will use will include:

Use Case <Number>: Title 
<Number>.1: <Summary/Goal> 
<Number>.2: <Actors> 
<Number>.3: <Preconditions> 
<Number>.4: <Main Path> 
<Number>.5: <Alternate Paths – including sub-flows [S] and error-flows [E]> 

Writing Use Case 1 in this format yields:

Use Case 1: Request a meeting 
1.1: Summary/Goal
User A can choose the date and time for a meeting with User B [Main]. User A can choose User B as the recipient of the meeting
request [Main], or multiple Users as the recipient [S.2]. User A sends the meeting request to User B through the system [Main].
Before User A sends the meeting request, User A can opt not to send the request and delete it [S.1]. If User B is no longer in
the system, User A receives notification that the meeting request cannot be sent [E.1]. 
1.2: Actors
Users 
1.3: Preconditions
- User A and User B are recorded as Users in the system
- User A has logged into the system 
1.4: Main Path
1) User A chooses a date for a meeting
2) User A chooses a time for a meeting
3) User A chooses User B as the recipient for the meeting request
4) User A submits the meeting request
5) User B receives the meeting request the next time User B logs into the system 
1.5: Alternative Path
S.1
User A creates a meeting request, but down not submit it. A meeting request is not sent to User B 
S.2
User A creates a meeting request for more than one User. User A submits the meeting request and each User receives it the next
time they log in 
E.1
User B is no longer a User in the system. User A receives notification that the meeting request cannot be sent. 

==== Results ====
There are a few interesting things revealed about the system by re-writing the Use Case in this format. The most important is likely that Users will need to "log-in" to the system. This implies that there could be another Actor in the system, namely an Admin. This leads to these additional Use Cases:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>5</td>
<td>Log into the system</td>
<td>User</td>
</tr>
<tr>
<td>6</td>
<td>Create a User in the system</td>
<td>Admin</td>
</tr>
</table>

Each of these new Use Cases would then go through the iterations listed above until they are in the template form. 

As you can see from the example, each iteration refines the Use Case and helps to clarify the requirements of the system.

== Use Case Diagrams ==

Use Case Diagrams are useful for showing how each component in a system will interact with other components of the system [SOURCE]. They are not good for showing the flow of events that a system will have, like the written Use Cases are [SOURCE]. Also, unlike written Use Cases, Use Case Diagrams use UML so that there is a standard.

DEFINE UML HERE

=== Components of a Use Case Diagram ===

UCDs have only 4 major elements: The actors that the system you are describing interacts with, the system itself, the use cases, or services, that the system knows how to perform, and the lines that represent relationships between these elements.[SOURCE: http://www.andrew.cmu.edu/course/90-754/umlucdfaq.html#uses – DIRECT QUOTE]

'''Actors''' in Use Case Diagrams are represented by stick figures:

[[Image:Actor.png]]

'''Use Cases''' are represented by ovals:

[[Image:UseCase.png]]

'''Relationships''' are represented by Solid Lines. Sometimes, arrowheads are added to the lines to indicate the direction of the invocation, or to show which actor is the primary actor [SOURCE: http://www.agilemodeling.com/artifacts/useCaseDiagram.htm]

[[Image:Lines.png]]

Two special relationships that can be shown in a Use Case Diagram are the ''Extends'' and ''Includes'' relationships. These relationships are usually shown with a dotted line with an arrowhead and <<extend>> or <<include>> written near the line.

The ''Extends'' relationship is used to show when Use Case X is a special case of Use Case Y [SOURCE]. In this situation, the dotted line is drawn from Use Case X to Use Case Y with the arrowhead pointing to Use Case Y.

The ''Includes/Uses'' relationship is used to show that every time Use Case X is done, Use Case Y must also be done [SOURCE]. In this case, the arrow points to Use Case Y.

=== Creating a Use Case Diagram ===

A Use Case Diagram for the same system described in the Writing a Use Case might look something like:

[[Image:UCDiagram.png]]

As you can see, "Accept Meeting" and "Suggest new time" are special cases of "Respond to request". Also, from this diagram, the system designers are saying that in order to "Request a Meeting" the user must "View Schedule".

== Advanced Topics ==

===Essential Use Cases Vs System Use cases===
[http://en.wikipedia.org/wiki/Use_case]
Use cases may be described at the abstract level (business use case, sometimes called essential use case), or at the system level (system use case). The difference between these is the scope.

<ul>
<li>A business use case is described in technology-free terminology which treats system as a black box and describes the business process that is used by its business actors (people or systems external to the process) to achieve their goals (e.g., manual payment processing, expense report approval, manage corporate real estate). The business use case will describe a process that provides value to the business actor, and it describes what the process does. Business Process Mapping is another method for this level of business description. A significant advantage of essential use cases is that they enable you to stand back and ask fundamental questions like "what's really going on" and "what do we really need to do" without letting implementation decisions get in the way. These questions often lead to critical realizations that allow you to rethink, or reengineer if you prefer that term, aspects of the overall business process.
A Very good example of essential use case can be seen in this link: http://www.agilemodeling.com/artifacts/essentialUseCase.htm </li>
<li>A system use case describes a system that automates a business use case or process. It is normally described at the system functionality level (for example, "create voucher") and specifies the function or the service that the system provides for the actor. The system use case details what the system will do in response to an actor's actions. For this reason it is recommended that system use case specification begin with a verb (e.g., create voucher, select payments, exclude payment, cancel voucher). An actor can be a human user or another system/subsystem interacting with the system being defined</li>
</ul>

===Pluggable Use Cases:===
[http://alistair.cockburn.us/Pluggable+use+cases]
Use cases describe various scenarios and sequence of operations to achieve a given goal between actors and systems. We have seen that we can write Use Cases in various styles with varying degrees of details, varying aims and for varying audience in terms of business and System use cases. Business use cases are very readable with very little technical content so that stakeholders and business managers can understand the system as a black box. This may not work with the developers. They would like to see more technical details and have use cases that describe fully what a system must do under all circumstances.

It has been seen through experience that there is some amount of common behavior that is replicated in many business use cases. By extracting these common processing details (e.g. create, read, update, delete, etc), the contents of use cases can be reduced. These common processing details can be put into what is called lower level pluggable use cases. Essentially, we are creating various levels of use cases. At the highest level, what we can call as the main use case shows the more fundamental processing steps with the names of the pluggable use cases 'plugged' in-between. This helps abstracting out lower level details and keeping the use cases more simple. What this also does is, business managers and stake holders can see the higher level use case which still remains simple and readable whereas the lower level details which are of interest to developers is not lost either. These use case levels provides the freedom of reading at various degrees of granularity.

Pluggable use cases have to be written in a generic form so that it can be used wherever needed. It should be generic enough that it can be plugged into other use cases. All the rules of a regular use cases still apply in terms of finding goals(which are essentially sub goals of the system), actors etc.
Pluggable use cases can be produced in a way where their content is the same for all transactions, that is, it is common to various scenarios and projects. The difference in each project or scenario is mainly the data they handle and the sequence of activities being performed. The unique data and rules of each scenario are separated and documented independently in "Companion Tables" from the process steps which enable flexibility and maximum reuse.


Thus pluggable use cases become building blocks for higher level use cases. They are organized and applied within each use case to reach its goals. Whenever a pluggable use case is invoked, the invocation references the companion table that provides the unique data and rules for that use case. They are most effective when they are used in conjunction with these tables.

Use case content is dependent on the requirements of the system under design. This is also true for pluggable use cases. While the majority of pluggable use case content can be used verbatim across any project or company, minor customizations may be needed to accommodate the individual needs of the project and company.

Some use case sequences are simple while others are complex. To manage degrees of complexity, a use case can exercise one, multiple or a series of pluggable use cases wherever desired and in any order. To maximize use case cohesion and increase reusability a pluggable use case may employ another pluggable use case. The versatility of pluggable use cases provides a solid foundation for the construction of project use cases. 

The following link has excellent examples of how pluggable use cases can be written and used http://alistair.cockburn.us/Pluggable+use+cases

== Tools and Examples ==

=== Tools ===

There are many different tools available to create Use Cases. For a more comprehensive list, go to [http://en.wikipedia.org/wiki/List_of_Unified_Modeling_Language_tools Wikipedia's list of UML modeling tools]. A sampling are below: 
<ul>
<li>'''Rational Rose:'''

One of the most popular tool for use-case driven development.

http://www-306.ibm.com/software/awdtools/developer/rose/index.html</li>

<li>'''Sun Java Studio Enterprise:'''

Sun Java Studio Enterprise offers a UML tool.

http://developers.sun.com/jsenterprise/</li>

<li>'''Visual case:'''

UML & E/R Database Design Tool

http://www.visualcase.com/</li>

</ul>

=== Examples ===
There are many different examples of Use Cases. Some are listed below: 
<ul>
<li> http://www.objectmentor.com/resources/articles/usecases.pdf </li>
<li> http://www.w3.org/2002/06/ws-example </li>
<li> http://www.agilemodeling.com/essays/useCaseReuse.htm </li>
<li> http://www.soi.wide.ad.jp/class/20040034/slides/07/9.html </li>
<li> http://www.cs.colorado.edu/~kena/classes/6448/s05/reference/usecases/examples.html </li>
<li> http://courses.softlab.ntua.gr/softeng/Tutorials/UML-Use-Cases.pdf </li>
</ul>
== Further Reading ==

== References ==

CSC/ECE 517 Fall 2010/ch4 4a RJ

2010-10-20T04:18:30Z

Bazinga: /* Use Case Basics */

Use Cases 
== Introduction ==
== Use Case Basics ==

Use cases can be defined in many ways. There are many formal definitions for it. Very simply put, a use case is a reason to use a system. For example, a student borrowing a book from a library would be a use case of the library or a bank cardholder might need to use an ATM to get cash out of their account. More formally, “a use case is a collection of possible sequences of interactions between the system under discussion and its Users (or Actors), relating to a particular goal” [http://alistair.cockburn.us/Use+case+fundamentals].

A use case is initiated by a user with a particular goal in mind, and completes successfully when that goal is satisfied. The system is treated as a "black box", and the interactions with system, including system responses, are as perceived from outside the system.

Use cases capture who (actor) does what (interaction) with the system, for what purpose (goal), without dealing with system internals. A complete set of use cases specifies all the different ways to use the system, and therefore defines all behavior required of the system, bounding the scope of the system.[http://www.bredemeyer.com/use_cases.htm]

===Terms used with Use cases===
Now let us define some terms used with use cases: [http://en.wikipedia.org/wiki/Use_case]
<ol>
<li>Actor: An actor is a type of user that interacts with the system (ex student borrowing book or cardholder using ATM). Actors are also external entities (people or other systems) who interact with the system to achieve a desired goal. The goal must be of value to the actor.</li>

<li>Goal: Without a goal a use case is useless. There is no need for a use case when there is no need for any actor to achieve a goal. A goal briefly describes what the user intends to achieve with this use case. For example, the goal of a student using the library is to obtain the book. There is no point in having a use case like “the student enters the library” as that in itself has no value to the actor.</li>

<li>Stakeholder: A stakeholder is an individual or department that is affected by the outcome of the use case. Individuals are usually agents of the organization or department for which the use case is being created. A stakeholder might be called on to provide input, feedback, or authorization for the use case. The stakeholder section of the use case can include a brief description of which of these functions the stakeholder is assigned to fulfill.</li>
<li>Trigger: A trigger describes the event that causes the use case to be initiated. This event can be external or internal. If the trigger is not a simple true "event" (e.g., the customer presses a button), but instead "when a set of conditions are met", there will need to be a triggering process that continually (or periodically) runs to test whether the "trigger conditions" are met: the "triggering event" is a signal from the trigger process that the conditions are now met.
In our example with the student, a trigger would be the need for the book due to an approaching exam or test which causes the student to go to the library to borrow a book.
</li>

<li>Precondition: A precondition defines all the conditions that must be true (i.e., describes the state of the system) for the trigger to meaningfully cause the initiation of the use case. That is, if the system is not in the state described in the preconditions, the behavior of the use case is indeterminate. For example, the student should be a member of the library and have the required identity to borrow a book. If the student is not a member of the library, there is no point in the student trying to borrow a book from that library.</li>

<li>Scenarios: A scenario usually specifies when the use case starts and ends. It describes the interaction with actors and shows the flow of events between a user and system. For example, when a student tries to borrow a particular book from the library, it doesn’t always necessarily turn out the same way. Sometimes the book is available and sometimes it is already borrowed by someone else or the library may not have a given book. These are all examples of use case scenarios. The outcome in each case if different depending on circumstances, but they all relate to the same goal that is, they are all triggered by the same need(in this case, need for the book) and all the scenarios have the same starting point.</li>
</ol>

===Simple Example===
Now that we know something about use cases, let us go ahead and describe a simple use case:
Use Case 1: Request book from the library (automated system).

1.1: Summary/Goal
To borrow book a particular book from the library
1.2: Actors
Student
1.3: Preconditions
Student should be a member of the library and have an id.
1.4: Main Path
System requests for student ID and checks if he/she is a member
Student selects “request book”
Student enters name(s) of the book(s)
System checks for availability of books and displays results accordingly
Student confirms the order
System displays details of where the requested books are stacked
1.5: Alternate Path
System does not recognize Id or student is not a member. System will not allow any books to be checked out.
All books requested are already checked out. Displays this information to student and closes request.

===Important Characteristics of Use Cases===
The above description shows a very simple use case. However, there are a few essential characteristics to be noticed about the use case:
<ol>
<li>We have identified the key components of a use case, that is, the goal, actors, preconditions, key scenarios/flow and preconditions. It is very essential that we identify these components before writing a use case.</li>
<li>We have not gone into any sort of technical details about implementation or user interface design. Use cases only represent a very high level design. We are only trying to understand the flow and uses of the system.</li>
<li>We have recorded a set of paths (scenarios) that traverse an actor from a trigger event (start of the use case) to the goal (success scenarios).</li>
<li>We have recorded a set of scenarios that traverse an actor from a trigger event toward a goal but fall short of the goal (failure scenarios).</li>
</ol>

===Where can we use ‘use cases’?===

<ol>
<li>Use cases are usually used to capture the requirements of an interaction based system. When there is a lot of interaction between actors and the system, it makes sense to capture as many interactions and scenarios possible before starting development of the system.</li>
<li>Use cases help to eliminate rework due to requirements misunderstandings between developers and stakeholders by aiming to reach a point where there are no surprises for the users. Use cases help to build an explicit shared understanding that everyone can take away with them, the users, developers, testers, technical authors, and others.</li>
<li>Use cases have received some interest as a starting point for test design. By analyzing use cases for the system, we can know various interactions between the system and actors which will help in drawing out test plans.</li>
</ol>
===Where can’t we use ‘use cases’?===
[ http://en.wikipedia.org/wiki/Use_case]

<ol>
<li>Use case flows are not well suited to easily capturing non-interaction based requirements of a system (such as algorithm or mathematical requirements) or non-functional requirements (such as platform, performance, timing, or safety-critical aspects). These are better specified declaratively elsewhere.</li>
<li>Some systems are better described in an information/data-driven approach than in a functionality-driven approach of use cases. A good example of this kind of system is data-mining systems used for Business Intelligence. If you were to describe this kind of system in a use case model, it would be quite small and uninteresting (there are not many different functions here) but the set of data that the system handles may nevertheless be large and rich in details.</li>
</ol>

===Common mistakes while writing Use cases: ===

<ol>
<li>The system boundary is undefined or inconstant. A system boundary is a boundary that separates the internal components of a system from external entities. If we are not able to identify the system boundaries, we will not be able to clearly define the actors, scenarios and other essential factors involved in writing a good and useful use case. For example, the system described in the library example, has a clear boundary. It is used to accept inputs as book names, checks the id and provides a location for the books. We know its role very clearly. Suppose the system was used to manage everything like security, employee details etc, we will not be able to identify the goal, actors and scenarios very clearly.</li>
<li>Use cases should not be used to capture all the details of a system. The granularity to which you define use cases in a diagram should be enough to keep the use case diagram uncluttered and readable, yet, be complete without missing significant aspects of the required functionality.</li>
<li>The use cases are written from the system’s (not the actors’) point of view. Use cases written from a system point of view will make the writer have the tendency to get into technical details. If we wrote the example test case above from the systems point of view, we would have statements like “obtain location of book from database and display location of books to user”. This is more detail than necessary. Also, this would not capture the interaction with the actor very clearly. Use cases also give a brief insight into how the UI should look but when written from the system these details might not be captured clearly.</li>
</ol>

== Writing Use Cases ==
Writing Use Cases for a system is a process taken between those designing the system and the Stakeholders. There are many different ways to write Use Cases [SOURCE]. Because of this, there are many different formats that Use Cases can take when they are written. There are, however, certain guidelines that should be followed in the process of writing Use Cases. In general, these guidelines are:
<ol>
<li>Never include implementation specific terminology in the Use Case [SOURCE]</li>
<li>Each Use Case should be a set of scenarios, which include different flows of events [SOURCE]</li>
</ol>
=== Iterative Process ===
Normally, this process is done iteratively, so that the iterations can build upon each other [SOURCE]. Below is an example of three iterations of the Use Case writing process to illustrate how it can reveal things about a system and layout the functional requirements. 

For this example, we will be creating Use Cases to solve the following problem statement:

Develop a system to allow users to schedule meetings with each other.

In this system, the stakeholders will be the users of the system. The Users will also be the only Actors in the system. 

==== Iteration 1 ====
For the first iteration, we will write out short sentences to describe the functionality that the system will have. Some use cases could be:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>1</td>
<td>Request a Meeting</td>
<td>User</td>
</tr>
<tr>
<td>2</td>
<td>Approve a meeting request</td>
<td>User</td>
</tr>
<tr>
<td>3</td>
<td>Suggest a new time</td>
<td>User</td>
</tr>
<tr>
<td>4</td>
<td>View a User's schedule</td>
<td>User</td>
</tr>
</table>

In this example, the fourth Use Case may not have been an obvious requirement that could be derived from the original problem statement, but in the process of creating the Use Cases, it was discovered that it would be a good requirement for the system to have.

==== Iteration 2 ====

The next iteration would involve writing out longer descriptions for each. This could be done in paragraph form, or by writing a list. Below are the Use Cases in paragraph form:

'''Use Case 1 – Request a meeting'''
User A chooses the date and time for a meeting with User B. User A chooses User B as the recipient of the meeting request.
User A sends the meeting request to User B through the system. 
'''Use Case 2 – Approve a Meeting Request'''
User A receives a meeting request from User B and accepts the user request. A notification that User A has accepted the meeting is sent to User B. 
'''Use Case 3 – Suggest a different meeting time'''
User A receives a meeting request from User B and suggests a different time and/or date for the meeting. The response is sent to User B through
the system. 
'''Use Case 4 – View a User's schedule'''
User A would like to schedule a meeting with User B. User A starts the system and opens up User B's schedule.
User A can see when User B has already scheduled meetings and User A can then use that information to send User B a meeting request.
Use A can also access their own schedule to view when User A has scheduled meetings. 

From writing out the Use Cases with more description, it should become clear that Use Case 2 and Use Case 3 are very similar. In both Use Cases, User A responds to a meeting request and a response/notification is sent to User B. This might lead the designers of the system to combine these two Use Cases into one Use Case for "Respond to Request."

==== Iteration 3 ====

In the next iteration, we're going to use a Use Case template. There are many different Use Case templates, which include different information [SOURCES]. A template can be created that is unique for the system being described, provided each Use Case uses the same template. The template we will use will include:

Use Case <Number>: Title 
<Number>.1: <Summary/Goal> 
<Number>.2: <Actors> 
<Number>.3: <Preconditions> 
<Number>.4: <Main Path> 
<Number>.5: <Alternate Paths – including sub-flows [S] and error-flows [E]> 

Writing Use Case 1 in this format yields:

Use Case 1: Request a meeting 
1.1: Summary/Goal
User A can choose the date and time for a meeting with User B [Main]. User A can choose User B as the recipient of the meeting
request [Main], or multiple Users as the recipient [S.2]. User A sends the meeting request to User B through the system [Main].
Before User A sends the meeting request, User A can opt not to send the request and delete it [S.1]. If User B is no longer in
the system, User A receives notification that the meeting request cannot be sent [E.1]. 
1.2: Actors
Users 
1.3: Preconditions
- User A and User B are recorded as Users in the system
- User A has logged into the system 
1.4: Main Path
1) User A chooses a date for a meeting
2) User A chooses a time for a meeting
3) User A chooses User B as the recipient for the meeting request
4) User A submits the meeting request
5) User B receives the meeting request the next time User B logs into the system 
1.5: Alternative Path
S.1
User A creates a meeting request, but down not submit it. A meeting request is not sent to User B 
S.2
User A creates a meeting request for more than one User. User A submits the meeting request and each User receives it the next
time they log in 
E.1
User B is no longer a User in the system. User A receives notification that the meeting request cannot be sent. 

==== Results ====
There are a few interesting things revealed about the system by re-writing the Use Case in this format. The most important is likely that Users will need to "log-in" to the system. This implies that there could be another Actor in the system, namely an Admin. This leads to these additional Use Cases:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>5</td>
<td>Log into the system</td>
<td>User</td>
</tr>
<tr>
<td>6</td>
<td>Create a User in the system</td>
<td>Admin</td>
</tr>
</table>

Each of these new Use Cases would then go through the iterations listed above until they are in the template form. 

As you can see from the example, each iteration refines the Use Case and helps to clarify the requirements of the system.

== Use Case Diagrams ==

Use Case Diagrams are useful for showing how each component in a system will interact with other components of the system [SOURCE]. They are not good for showing the flow of events that a system will have, like the written Use Cases are [SOURCE]. Also, unlike written Use Cases, Use Case Diagrams use UML so that there is a standard.

DEFINE UML HERE

=== Components of a Use Case Diagram ===

UCDs have only 4 major elements: The actors that the system you are describing interacts with, the system itself, the use cases, or services, that the system knows how to perform, and the lines that represent relationships between these elements.[SOURCE: http://www.andrew.cmu.edu/course/90-754/umlucdfaq.html#uses – DIRECT QUOTE]

'''Actors''' in Use Case Diagrams are represented by stick figures:

[[Image:Actor.png]]

'''Use Cases''' are represented by ovals:

[[Image:UseCase.png]]

'''Relationships''' are represented by Solid Lines. Sometimes, arrowheads are added to the lines to indicate the direction of the invocation, or to show which actor is the primary actor [SOURCE: http://www.agilemodeling.com/artifacts/useCaseDiagram.htm]

[[Image:Lines.png]]

Two special relationships that can be shown in a Use Case Diagram are the ''Extends'' and ''Includes'' relationships. These relationships are usually shown with a dotted line with an arrowhead and <<extend>> or <<include>> written near the line.

The ''Extends'' relationship is used to show when Use Case X is a special case of Use Case Y [SOURCE]. In this situation, the dotted line is drawn from Use Case X to Use Case Y with the arrowhead pointing to Use Case Y.

The ''Includes/Uses'' relationship is used to show that every time Use Case X is done, Use Case Y must also be done [SOURCE]. In this case, the arrow points to Use Case Y.

=== Creating a Use Case Diagram ===

A Use Case Diagram for the same system described in the Writing a Use Case might look something like:

[[Image:UCDiagram.png]]

As you can see, "Accept Meeting" and "Suggest new time" are special cases of "Respond to request". Also, from this diagram, the system designers are saying that in order to "Request a Meeting" the user must "View Schedule".

== Advanced Topics ==
== Tools and Examples ==

=== Tools ===

There are many different tools available to create Use Cases. For a more comprehensive list, go to [http://en.wikipedia.org/wiki/List_of_Unified_Modeling_Language_tools Wikipedia's list of UML modeling tools]. A sampling are below: 
<ul>
<li>'''Rational Rose:'''

One of the most popular tool for use-case driven development.

http://www-306.ibm.com/software/awdtools/developer/rose/index.html</li>

<li>'''Sun Java Studio Enterprise:'''

Sun Java Studio Enterprise offers a UML tool.

http://developers.sun.com/jsenterprise/</li>

<li>'''Visual case:'''

UML & E/R Database Design Tool

http://www.visualcase.com/</li>

</ul>

=== Examples ===
There are many different examples of Use Cases. Some are listed below: 
<ul>
<li> http://www.objectmentor.com/resources/articles/usecases.pdf </li>
<li> http://www.w3.org/2002/06/ws-example </li>
<li> http://www.agilemodeling.com/essays/useCaseReuse.htm </li>
<li> http://www.soi.wide.ad.jp/class/20040034/slides/07/9.html </li>
<li> http://www.cs.colorado.edu/~kena/classes/6448/s05/reference/usecases/examples.html </li>
<li> http://courses.softlab.ntua.gr/softeng/Tutorials/UML-Use-Cases.pdf </li>
</ul>
== Further Reading ==

== References ==

CSC/ECE 517 Fall 2010/ch4 4a RJ

2010-10-20T04:17:41Z

Bazinga: /* Use Case Basics */

Use Cases 
== Introduction ==
== Use Case Basics ==

Use cases can be defined in many ways. There are many formal definitions for it. Very simply put, a use case is a reason to use a system. For example, a student borrowing a book from a library would be a use case of the library or a bank cardholder might need to use an ATM to get cash out of their account. More formally, “a use case is a collection of possible sequences of interactions between the system under discussion and its Users (or Actors), relating to a particular goal” [http://alistair.cockburn.us/Use+case+fundamentals].

A use case is initiated by a user with a particular goal in mind, and completes successfully when that goal is satisfied. The system is treated as a "black box", and the interactions with system, including system responses, are as perceived from outside the system.

Use cases capture who (actor) does what (interaction) with the system, for what purpose (goal), without dealing with system internals. A complete set of use cases specifies all the different ways to use the system, and therefore defines all behavior required of the system, bounding the scope of the system.[http://www.bredemeyer.com/use_cases.htm]

===Terms used with Use cases===
Now let us define some terms used with use cases: [http://en.wikipedia.org/wiki/Use_case]
<ol>
<li>Actor: An actor is a type of user that interacts with the system (ex student borrowing book or cardholder using ATM). Actors are also external entities (people or other systems) who interact with the system to achieve a desired goal. The goal must be of value to the actor.</li>

<li>Goal: Without a goal a use case is useless. There is no need for a use case when there is no need for any actor to achieve a goal. A goal briefly describes what the user intends to achieve with this use case. For example, the goal of a student using the library is to obtain the book. There is no point in having a use case like “the student enters the library” as that in itself has no value to the actor.</li>

<li>Stakeholder: A stakeholder is an individual or department that is affected by the outcome of the use case. Individuals are usually agents of the organization or department for which the use case is being created. A stakeholder might be called on to provide input, feedback, or authorization for the use case. The stakeholder section of the use case can include a brief description of which of these functions the stakeholder is assigned to fulfill.</li>
<li>Trigger: A trigger describes the event that causes the use case to be initiated. This event can be external or internal. If the trigger is not a simple true "event" (e.g., the customer presses a button), but instead "when a set of conditions are met", there will need to be a triggering process that continually (or periodically) runs to test whether the "trigger conditions" are met: the "triggering event" is a signal from the trigger process that the conditions are now met.
In our example with the student, a trigger would be the need for the book due to an approaching exam or test which causes the student to go to the library to borrow a book.
</li>

<li>Precondition: A precondition defines all the conditions that must be true (i.e., describes the state of the system) for the trigger to meaningfully cause the initiation of the use case. That is, if the system is not in the state described in the preconditions, the behavior of the use case is indeterminate. For example, the student should be a member of the library and have the required identity to borrow a book. If the student is not a member of the library, there is no point in the student trying to borrow a book from that library.</li>

<li>Scenarios: A scenario usually specifies when the use case starts and ends. It describes the interaction with actors and shows the flow of events between a user and system. For example, when a student tries to borrow a particular book from the library, it doesn’t always necessarily turn out the same way. Sometimes the book is available and sometimes it is already borrowed by someone else or the library may not have a given book. These are all examples of use case scenarios. The outcome in each case if different depending on circumstances, but they all relate to the same goal that is, they are all triggered by the same need(in this case, need for the book) and all the scenarios have the same starting point.</li>
</ol>

Now that we know something about use cases, let us go ahead and describe a simple use case:
Use Case 1: Request book from the library (automated system).

1.1: Summary/Goal
To borrow book a particular book from the library
1.2: Actors
Student
1.3: Preconditions
Student should be a member of the library and have an id.
1.4: Main Path
System requests for student ID and checks if he/she is a member
Student selects “request book”
Student enters name(s) of the book(s)
System checks for availability of books and displays results accordingly
Student confirms the order
System displays details of where the requested books are stacked
1.5: Alternate Path
System does not recognize Id or student is not a member. System will not allow any books to be checked out.
All books requested are already checked out. Displays this information to student and closes request.

The above description shows a very simple use case. However, there are a few essential characteristics to be noticed about the use case:
<ol>
<li>We have identified the key components of a use case, that is, the goal, actors, preconditions, key scenarios/flow and preconditions. It is very essential that we identify these components before writing a use case.</li>
<li>We have not gone into any sort of technical details about implementation or user interface design. Use cases only represent a very high level design. We are only trying to understand the flow and uses of the system.</li>
<li>We have recorded a set of paths (scenarios) that traverse an actor from a trigger event (start of the use case) to the goal (success scenarios).</li>
<li>We have recorded a set of scenarios that traverse an actor from a trigger event toward a goal but fall short of the goal (failure scenarios).</li>
</ol>

===Where can we use ‘use cases’?===

<ol>
<li>Use cases are usually used to capture the requirements of an interaction based system. When there is a lot of interaction between actors and the system, it makes sense to capture as many interactions and scenarios possible before starting development of the system.</li>
<li>Use cases help to eliminate rework due to requirements misunderstandings between developers and stakeholders by aiming to reach a point where there are no surprises for the users. Use cases help to build an explicit shared understanding that everyone can take away with them, the users, developers, testers, technical authors, and others.</li>
<li>Use cases have received some interest as a starting point for test design. By analyzing use cases for the system, we can know various interactions between the system and actors which will help in drawing out test plans.</li>
</ol>
===Where can’t we use ‘use cases’?===
[ http://en.wikipedia.org/wiki/Use_case]

<ol>
<li>Use case flows are not well suited to easily capturing non-interaction based requirements of a system (such as algorithm or mathematical requirements) or non-functional requirements (such as platform, performance, timing, or safety-critical aspects). These are better specified declaratively elsewhere.</li>
<li>Some systems are better described in an information/data-driven approach than in a functionality-driven approach of use cases. A good example of this kind of system is data-mining systems used for Business Intelligence. If you were to describe this kind of system in a use case model, it would be quite small and uninteresting (there are not many different functions here) but the set of data that the system handles may nevertheless be large and rich in details.</li>
</ol>

===Common mistakes while writing Use cases: ===

<ol>
<li>The system boundary is undefined or inconstant. A system boundary is a boundary that separates the internal components of a system from external entities. If we are not able to identify the system boundaries, we will not be able to clearly define the actors, scenarios and other essential factors involved in writing a good and useful use case. For example, the system described in the library example, has a clear boundary. It is used to accept inputs as book names, checks the id and provides a location for the books. We know its role very clearly. Suppose the system was used to manage everything like security, employee details etc, we will not be able to identify the goal, actors and scenarios very clearly.</li>
<li>Use cases should not be used to capture all the details of a system. The granularity to which you define use cases in a diagram should be enough to keep the use case diagram uncluttered and readable, yet, be complete without missing significant aspects of the required functionality.</li>
<li>The use cases are written from the system’s (not the actors’) point of view. Use cases written from a system point of view will make the writer have the tendency to get into technical details. If we wrote the example test case above from the systems point of view, we would have statements like “obtain location of book from database and display location of books to user”. This is more detail than necessary. Also, this would not capture the interaction with the actor very clearly. Use cases also give a brief insight into how the UI should look but when written from the system these details might not be captured clearly.</li>
</ol>

== Writing Use Cases ==
Writing Use Cases for a system is a process taken between those designing the system and the Stakeholders. There are many different ways to write Use Cases [SOURCE]. Because of this, there are many different formats that Use Cases can take when they are written. There are, however, certain guidelines that should be followed in the process of writing Use Cases. In general, these guidelines are:
<ol>
<li>Never include implementation specific terminology in the Use Case [SOURCE]</li>
<li>Each Use Case should be a set of scenarios, which include different flows of events [SOURCE]</li>
</ol>
=== Iterative Process ===
Normally, this process is done iteratively, so that the iterations can build upon each other [SOURCE]. Below is an example of three iterations of the Use Case writing process to illustrate how it can reveal things about a system and layout the functional requirements. 

For this example, we will be creating Use Cases to solve the following problem statement:

Develop a system to allow users to schedule meetings with each other.

In this system, the stakeholders will be the users of the system. The Users will also be the only Actors in the system. 

==== Iteration 1 ====
For the first iteration, we will write out short sentences to describe the functionality that the system will have. Some use cases could be:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>1</td>
<td>Request a Meeting</td>
<td>User</td>
</tr>
<tr>
<td>2</td>
<td>Approve a meeting request</td>
<td>User</td>
</tr>
<tr>
<td>3</td>
<td>Suggest a new time</td>
<td>User</td>
</tr>
<tr>
<td>4</td>
<td>View a User's schedule</td>
<td>User</td>
</tr>
</table>

In this example, the fourth Use Case may not have been an obvious requirement that could be derived from the original problem statement, but in the process of creating the Use Cases, it was discovered that it would be a good requirement for the system to have.

==== Iteration 2 ====

The next iteration would involve writing out longer descriptions for each. This could be done in paragraph form, or by writing a list. Below are the Use Cases in paragraph form:

'''Use Case 1 – Request a meeting'''
User A chooses the date and time for a meeting with User B. User A chooses User B as the recipient of the meeting request.
User A sends the meeting request to User B through the system. 
'''Use Case 2 – Approve a Meeting Request'''
User A receives a meeting request from User B and accepts the user request. A notification that User A has accepted the meeting is sent to User B. 
'''Use Case 3 – Suggest a different meeting time'''
User A receives a meeting request from User B and suggests a different time and/or date for the meeting. The response is sent to User B through
the system. 
'''Use Case 4 – View a User's schedule'''
User A would like to schedule a meeting with User B. User A starts the system and opens up User B's schedule.
User A can see when User B has already scheduled meetings and User A can then use that information to send User B a meeting request.
Use A can also access their own schedule to view when User A has scheduled meetings. 

From writing out the Use Cases with more description, it should become clear that Use Case 2 and Use Case 3 are very similar. In both Use Cases, User A responds to a meeting request and a response/notification is sent to User B. This might lead the designers of the system to combine these two Use Cases into one Use Case for "Respond to Request."

==== Iteration 3 ====

In the next iteration, we're going to use a Use Case template. There are many different Use Case templates, which include different information [SOURCES]. A template can be created that is unique for the system being described, provided each Use Case uses the same template. The template we will use will include:

Use Case <Number>: Title 
<Number>.1: <Summary/Goal> 
<Number>.2: <Actors> 
<Number>.3: <Preconditions> 
<Number>.4: <Main Path> 
<Number>.5: <Alternate Paths – including sub-flows [S] and error-flows [E]> 

Writing Use Case 1 in this format yields:

Use Case 1: Request a meeting 
1.1: Summary/Goal
User A can choose the date and time for a meeting with User B [Main]. User A can choose User B as the recipient of the meeting
request [Main], or multiple Users as the recipient [S.2]. User A sends the meeting request to User B through the system [Main].
Before User A sends the meeting request, User A can opt not to send the request and delete it [S.1]. If User B is no longer in
the system, User A receives notification that the meeting request cannot be sent [E.1]. 
1.2: Actors
Users 
1.3: Preconditions
- User A and User B are recorded as Users in the system
- User A has logged into the system 
1.4: Main Path
1) User A chooses a date for a meeting
2) User A chooses a time for a meeting
3) User A chooses User B as the recipient for the meeting request
4) User A submits the meeting request
5) User B receives the meeting request the next time User B logs into the system 
1.5: Alternative Path
S.1
User A creates a meeting request, but down not submit it. A meeting request is not sent to User B 
S.2
User A creates a meeting request for more than one User. User A submits the meeting request and each User receives it the next
time they log in 
E.1
User B is no longer a User in the system. User A receives notification that the meeting request cannot be sent. 

==== Results ====
There are a few interesting things revealed about the system by re-writing the Use Case in this format. The most important is likely that Users will need to "log-in" to the system. This implies that there could be another Actor in the system, namely an Admin. This leads to these additional Use Cases:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>5</td>
<td>Log into the system</td>
<td>User</td>
</tr>
<tr>
<td>6</td>
<td>Create a User in the system</td>
<td>Admin</td>
</tr>
</table>

Each of these new Use Cases would then go through the iterations listed above until they are in the template form. 

As you can see from the example, each iteration refines the Use Case and helps to clarify the requirements of the system.

== Use Case Diagrams ==

Use Case Diagrams are useful for showing how each component in a system will interact with other components of the system [SOURCE]. They are not good for showing the flow of events that a system will have, like the written Use Cases are [SOURCE]. Also, unlike written Use Cases, Use Case Diagrams use UML so that there is a standard.

DEFINE UML HERE

=== Components of a Use Case Diagram ===

UCDs have only 4 major elements: The actors that the system you are describing interacts with, the system itself, the use cases, or services, that the system knows how to perform, and the lines that represent relationships between these elements.[SOURCE: http://www.andrew.cmu.edu/course/90-754/umlucdfaq.html#uses – DIRECT QUOTE]

'''Actors''' in Use Case Diagrams are represented by stick figures:

[[Image:Actor.png]]

'''Use Cases''' are represented by ovals:

[[Image:UseCase.png]]

'''Relationships''' are represented by Solid Lines. Sometimes, arrowheads are added to the lines to indicate the direction of the invocation, or to show which actor is the primary actor [SOURCE: http://www.agilemodeling.com/artifacts/useCaseDiagram.htm]

[[Image:Lines.png]]

Two special relationships that can be shown in a Use Case Diagram are the ''Extends'' and ''Includes'' relationships. These relationships are usually shown with a dotted line with an arrowhead and <<extend>> or <<include>> written near the line.

The ''Extends'' relationship is used to show when Use Case X is a special case of Use Case Y [SOURCE]. In this situation, the dotted line is drawn from Use Case X to Use Case Y with the arrowhead pointing to Use Case Y.

The ''Includes/Uses'' relationship is used to show that every time Use Case X is done, Use Case Y must also be done [SOURCE]. In this case, the arrow points to Use Case Y.

=== Creating a Use Case Diagram ===

A Use Case Diagram for the same system described in the Writing a Use Case might look something like:

[[Image:UCDiagram.png]]

As you can see, "Accept Meeting" and "Suggest new time" are special cases of "Respond to request". Also, from this diagram, the system designers are saying that in order to "Request a Meeting" the user must "View Schedule".

== Advanced Topics ==
== Tools and Examples ==

=== Tools ===

There are many different tools available to create Use Cases. For a more comprehensive list, go to [http://en.wikipedia.org/wiki/List_of_Unified_Modeling_Language_tools Wikipedia's list of UML modeling tools]. A sampling are below: 
<ul>
<li>'''Rational Rose:'''

One of the most popular tool for use-case driven development.

http://www-306.ibm.com/software/awdtools/developer/rose/index.html</li>

<li>'''Sun Java Studio Enterprise:'''

Sun Java Studio Enterprise offers a UML tool.

http://developers.sun.com/jsenterprise/</li>

<li>'''Visual case:'''

UML & E/R Database Design Tool

http://www.visualcase.com/</li>

</ul>

=== Examples ===
There are many different examples of Use Cases. Some are listed below: 
<ul>
<li> http://www.objectmentor.com/resources/articles/usecases.pdf </li>
<li> http://www.w3.org/2002/06/ws-example </li>
<li> http://www.agilemodeling.com/essays/useCaseReuse.htm </li>
<li> http://www.soi.wide.ad.jp/class/20040034/slides/07/9.html </li>
<li> http://www.cs.colorado.edu/~kena/classes/6448/s05/reference/usecases/examples.html </li>
<li> http://courses.softlab.ntua.gr/softeng/Tutorials/UML-Use-Cases.pdf </li>
</ul>
== Further Reading ==

== References ==

CSC/ECE 517 Fall 2010/ch4 4a RJ

2010-10-20T04:16:30Z

Bazinga: /* Use Case Basics */

Use Cases 
== Introduction ==
== Use Case Basics ==

Use cases can be defined in many ways. There are many formal definitions for it. Very simply put, a use case is a reason to use a system. For example, a student borrowing a book from a library would be a use case of the library or a bank cardholder might need to use an ATM to get cash out of their account. More formally, “a use case is a collection of possible sequences of interactions between the system under discussion and its Users (or Actors), relating to a particular goal” [http://alistair.cockburn.us/Use+case+fundamentals].

A use case is initiated by a user with a particular goal in mind, and completes successfully when that goal is satisfied. The system is treated as a "black box", and the interactions with system, including system responses, are as perceived from outside the system.

Use cases capture who (actor) does what (interaction) with the system, for what purpose (goal), without dealing with system internals. A complete set of use cases specifies all the different ways to use the system, and therefore defines all behavior required of the system, bounding the scope of the system.[http://www.bredemeyer.com/use_cases.htm]

Now let us define some terms used with use cases: [http://en.wikipedia.org/wiki/Use_case]
<ol>
<li>Actor: An actor is a type of user that interacts with the system (ex student borrowing book or cardholder using ATM). Actors are also external entities (people or other systems) who interact with the system to achieve a desired goal. The goal must be of value to the actor.</li>

<li>Goal: Without a goal a use case is useless. There is no need for a use case when there is no need for any actor to achieve a goal. A goal briefly describes what the user intends to achieve with this use case. For example, the goal of a student using the library is to obtain the book. There is no point in having a use case like “the student enters the library” as that in itself has no value to the actor.</li>

<li>Stakeholder: A stakeholder is an individual or department that is affected by the outcome of the use case. Individuals are usually agents of the organization or department for which the use case is being created. A stakeholder might be called on to provide input, feedback, or authorization for the use case. The stakeholder section of the use case can include a brief description of which of these functions the stakeholder is assigned to fulfill.</li>
<li>Trigger: A trigger describes the event that causes the use case to be initiated. This event can be external or internal. If the trigger is not a simple true "event" (e.g., the customer presses a button), but instead "when a set of conditions are met", there will need to be a triggering process that continually (or periodically) runs to test whether the "trigger conditions" are met: the "triggering event" is a signal from the trigger process that the conditions are now met.
In our example with the student, a trigger would be the need for the book due to an approaching exam or test which causes the student to go to the library to borrow a book.
</li>

<li>Precondition: A precondition defines all the conditions that must be true (i.e., describes the state of the system) for the trigger to meaningfully cause the initiation of the use case. That is, if the system is not in the state described in the preconditions, the behavior of the use case is indeterminate. For example, the student should be a member of the library and have the required identity to borrow a book. If the student is not a member of the library, there is no point in the student trying to borrow a book from that library.</li>

<li>Scenarios: A scenario usually specifies when the use case starts and ends. It describes the interaction with actors and shows the flow of events between a user and system. For example, when a student tries to borrow a particular book from the library, it doesn’t always necessarily turn out the same way. Sometimes the book is available and sometimes it is already borrowed by someone else or the library may not have a given book. These are all examples of use case scenarios. The outcome in each case if different depending on circumstances, but they all relate to the same goal that is, they are all triggered by the same need(in this case, need for the book) and all the scenarios have the same starting point.</li>
</ol>

Now that we know something about use cases, let us go ahead and describe a simple use case:
Use Case 1: Request book from the library (automated system).

1.1: Summary/Goal
To borrow book a particular book from the library
1.2: Actors
Student
1.3: Preconditions
Student should be a member of the library and have an id.
1.4: Main Path
System requests for student ID and checks if he/she is a member
Student selects “request book”
Student enters name(s) of the book(s)
System checks for availability of books and displays results accordingly
Student confirms the order
System displays details of where the requested books are stacked
1.5: Alternate Path
System does not recognize Id or student is not a member. System will not allow any books to be checked out.
All books requested are already checked out. Displays this information to student and closes request.

The above description shows a very simple use case. However, there are a few essential characteristics to be noticed about the use case:
<ol>
<li>We have identified the key components of a use case, that is, the goal, actors, preconditions, key scenarios/flow and preconditions. It is very essential that we identify these components before writing a use case.</li>
<li>We have not gone into any sort of technical details about implementation or user interface design. Use cases only represent a very high level design. We are only trying to understand the flow and uses of the system.</li>
<li>We have recorded a set of paths (scenarios) that traverse an actor from a trigger event (start of the use case) to the goal (success scenarios).</li>
<li>We have recorded a set of scenarios that traverse an actor from a trigger event toward a goal but fall short of the goal (failure scenarios).</li>
</ol>

===Where can we use ‘use cases’?===

<ol>
<li>Use cases are usually used to capture the requirements of an interaction based system. When there is a lot of interaction between actors and the system, it makes sense to capture as many interactions and scenarios possible before starting development of the system.</li>
<li>Use cases help to eliminate rework due to requirements misunderstandings between developers and stakeholders by aiming to reach a point where there are no surprises for the users. Use cases help to build an explicit shared understanding that everyone can take away with them, the users, developers, testers, technical authors, and others.</li>
<li>Use cases have received some interest as a starting point for test design. By analyzing use cases for the system, we can know various interactions between the system and actors which will help in drawing out test plans.</li>
</ol>
===Where can’t we use ‘use cases’?===
[ http://en.wikipedia.org/wiki/Use_case]

<ol>
<li>Use case flows are not well suited to easily capturing non-interaction based requirements of a system (such as algorithm or mathematical requirements) or non-functional requirements (such as platform, performance, timing, or safety-critical aspects). These are better specified declaratively elsewhere.</li>
<li>Some systems are better described in an information/data-driven approach than in a functionality-driven approach of use cases. A good example of this kind of system is data-mining systems used for Business Intelligence. If you were to describe this kind of system in a use case model, it would be quite small and uninteresting (there are not many different functions here) but the set of data that the system handles may nevertheless be large and rich in details.</li>
</ol>

===Common mistakes while writing Use cases: ===

<ol>
<li>The system boundary is undefined or inconstant. A system boundary is a boundary that separates the internal components of a system from external entities. If we are not able to identify the system boundaries, we will not be able to clearly define the actors, scenarios and other essential factors involved in writing a good and useful use case. For example, the system described in the library example, has a clear boundary. It is used to accept inputs as book names, checks the id and provides a location for the books. We know its role very clearly. Suppose the system was used to manage everything like security, employee details etc, we will not be able to identify the goal, actors and scenarios very clearly.</li>
<li>Use cases should not be used to capture all the details of a system. The granularity to which you define use cases in a diagram should be enough to keep the use case diagram uncluttered and readable, yet, be complete without missing significant aspects of the required functionality.</li>
<li>The use cases are written from the system’s (not the actors’) point of view. Use cases written from a system point of view will make the writer have the tendency to get into technical details. If we wrote the example test case above from the systems point of view, we would have statements like “obtain location of book from database and display location of books to user”. This is more detail than necessary. Also, this would not capture the interaction with the actor very clearly. Use cases also give a brief insight into how the UI should look but when written from the system these details might not be captured clearly.</li>
</ol>

== Writing Use Cases ==
Writing Use Cases for a system is a process taken between those designing the system and the Stakeholders. There are many different ways to write Use Cases [SOURCE]. Because of this, there are many different formats that Use Cases can take when they are written. There are, however, certain guidelines that should be followed in the process of writing Use Cases. In general, these guidelines are:
<ol>
<li>Never include implementation specific terminology in the Use Case [SOURCE]</li>
<li>Each Use Case should be a set of scenarios, which include different flows of events [SOURCE]</li>
</ol>
=== Iterative Process ===
Normally, this process is done iteratively, so that the iterations can build upon each other [SOURCE]. Below is an example of three iterations of the Use Case writing process to illustrate how it can reveal things about a system and layout the functional requirements. 

For this example, we will be creating Use Cases to solve the following problem statement:

Develop a system to allow users to schedule meetings with each other.

In this system, the stakeholders will be the users of the system. The Users will also be the only Actors in the system. 

==== Iteration 1 ====
For the first iteration, we will write out short sentences to describe the functionality that the system will have. Some use cases could be:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>1</td>
<td>Request a Meeting</td>
<td>User</td>
</tr>
<tr>
<td>2</td>
<td>Approve a meeting request</td>
<td>User</td>
</tr>
<tr>
<td>3</td>
<td>Suggest a new time</td>
<td>User</td>
</tr>
<tr>
<td>4</td>
<td>View a User's schedule</td>
<td>User</td>
</tr>
</table>

In this example, the fourth Use Case may not have been an obvious requirement that could be derived from the original problem statement, but in the process of creating the Use Cases, it was discovered that it would be a good requirement for the system to have.

==== Iteration 2 ====

The next iteration would involve writing out longer descriptions for each. This could be done in paragraph form, or by writing a list. Below are the Use Cases in paragraph form:

'''Use Case 1 – Request a meeting'''
User A chooses the date and time for a meeting with User B. User A chooses User B as the recipient of the meeting request.
User A sends the meeting request to User B through the system. 
'''Use Case 2 – Approve a Meeting Request'''
User A receives a meeting request from User B and accepts the user request. A notification that User A has accepted the meeting is sent to User B. 
'''Use Case 3 – Suggest a different meeting time'''
User A receives a meeting request from User B and suggests a different time and/or date for the meeting. The response is sent to User B through
the system. 
'''Use Case 4 – View a User's schedule'''
User A would like to schedule a meeting with User B. User A starts the system and opens up User B's schedule.
User A can see when User B has already scheduled meetings and User A can then use that information to send User B a meeting request.
Use A can also access their own schedule to view when User A has scheduled meetings. 

From writing out the Use Cases with more description, it should become clear that Use Case 2 and Use Case 3 are very similar. In both Use Cases, User A responds to a meeting request and a response/notification is sent to User B. This might lead the designers of the system to combine these two Use Cases into one Use Case for "Respond to Request."

==== Iteration 3 ====

In the next iteration, we're going to use a Use Case template. There are many different Use Case templates, which include different information [SOURCES]. A template can be created that is unique for the system being described, provided each Use Case uses the same template. The template we will use will include:

Use Case <Number>: Title 
<Number>.1: <Summary/Goal> 
<Number>.2: <Actors> 
<Number>.3: <Preconditions> 
<Number>.4: <Main Path> 
<Number>.5: <Alternate Paths – including sub-flows [S] and error-flows [E]> 

Writing Use Case 1 in this format yields:

Use Case 1: Request a meeting 
1.1: Summary/Goal
User A can choose the date and time for a meeting with User B [Main]. User A can choose User B as the recipient of the meeting
request [Main], or multiple Users as the recipient [S.2]. User A sends the meeting request to User B through the system [Main].
Before User A sends the meeting request, User A can opt not to send the request and delete it [S.1]. If User B is no longer in
the system, User A receives notification that the meeting request cannot be sent [E.1]. 
1.2: Actors
Users 
1.3: Preconditions
- User A and User B are recorded as Users in the system
- User A has logged into the system 
1.4: Main Path
1) User A chooses a date for a meeting
2) User A chooses a time for a meeting
3) User A chooses User B as the recipient for the meeting request
4) User A submits the meeting request
5) User B receives the meeting request the next time User B logs into the system 
1.5: Alternative Path
S.1
User A creates a meeting request, but down not submit it. A meeting request is not sent to User B 
S.2
User A creates a meeting request for more than one User. User A submits the meeting request and each User receives it the next
time they log in 
E.1
User B is no longer a User in the system. User A receives notification that the meeting request cannot be sent. 

==== Results ====
There are a few interesting things revealed about the system by re-writing the Use Case in this format. The most important is likely that Users will need to "log-in" to the system. This implies that there could be another Actor in the system, namely an Admin. This leads to these additional Use Cases:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>5</td>
<td>Log into the system</td>
<td>User</td>
</tr>
<tr>
<td>6</td>
<td>Create a User in the system</td>
<td>Admin</td>
</tr>
</table>

Each of these new Use Cases would then go through the iterations listed above until they are in the template form. 

As you can see from the example, each iteration refines the Use Case and helps to clarify the requirements of the system.

== Use Case Diagrams ==

Use Case Diagrams are useful for showing how each component in a system will interact with other components of the system [SOURCE]. They are not good for showing the flow of events that a system will have, like the written Use Cases are [SOURCE]. Also, unlike written Use Cases, Use Case Diagrams use UML so that there is a standard.

DEFINE UML HERE

=== Components of a Use Case Diagram ===

UCDs have only 4 major elements: The actors that the system you are describing interacts with, the system itself, the use cases, or services, that the system knows how to perform, and the lines that represent relationships between these elements.[SOURCE: http://www.andrew.cmu.edu/course/90-754/umlucdfaq.html#uses – DIRECT QUOTE]

'''Actors''' in Use Case Diagrams are represented by stick figures:

[[Image:Actor.png]]

'''Use Cases''' are represented by ovals:

[[Image:UseCase.png]]

'''Relationships''' are represented by Solid Lines. Sometimes, arrowheads are added to the lines to indicate the direction of the invocation, or to show which actor is the primary actor [SOURCE: http://www.agilemodeling.com/artifacts/useCaseDiagram.htm]

[[Image:Lines.png]]

Two special relationships that can be shown in a Use Case Diagram are the ''Extends'' and ''Includes'' relationships. These relationships are usually shown with a dotted line with an arrowhead and <<extend>> or <<include>> written near the line.

The ''Extends'' relationship is used to show when Use Case X is a special case of Use Case Y [SOURCE]. In this situation, the dotted line is drawn from Use Case X to Use Case Y with the arrowhead pointing to Use Case Y.

The ''Includes/Uses'' relationship is used to show that every time Use Case X is done, Use Case Y must also be done [SOURCE]. In this case, the arrow points to Use Case Y.

=== Creating a Use Case Diagram ===

A Use Case Diagram for the same system described in the Writing a Use Case might look something like:

[[Image:UCDiagram.png]]

As you can see, "Accept Meeting" and "Suggest new time" are special cases of "Respond to request". Also, from this diagram, the system designers are saying that in order to "Request a Meeting" the user must "View Schedule".

== Advanced Topics ==
== Tools and Examples ==

=== Tools ===

There are many different tools available to create Use Cases. For a more comprehensive list, go to [http://en.wikipedia.org/wiki/List_of_Unified_Modeling_Language_tools Wikipedia's list of UML modeling tools]. A sampling are below: 
<ul>
<li>'''Rational Rose:'''

One of the most popular tool for use-case driven development.

http://www-306.ibm.com/software/awdtools/developer/rose/index.html</li>

<li>'''Sun Java Studio Enterprise:'''

Sun Java Studio Enterprise offers a UML tool.

http://developers.sun.com/jsenterprise/</li>

<li>'''Visual case:'''

UML & E/R Database Design Tool

http://www.visualcase.com/</li>

</ul>

=== Examples ===
There are many different examples of Use Cases. Some are listed below: 
<ul>
<li> http://www.objectmentor.com/resources/articles/usecases.pdf </li>
<li> http://www.w3.org/2002/06/ws-example </li>
<li> http://www.agilemodeling.com/essays/useCaseReuse.htm </li>
<li> http://www.soi.wide.ad.jp/class/20040034/slides/07/9.html </li>
<li> http://www.cs.colorado.edu/~kena/classes/6448/s05/reference/usecases/examples.html </li>
<li> http://courses.softlab.ntua.gr/softeng/Tutorials/UML-Use-Cases.pdf </li>
</ul>
== Further Reading ==

== References ==

CSC/ECE 517 Fall 2010/ch4 4a RJ

2010-10-20T04:14:40Z

Bazinga: /* Use Case Basics */

Use Cases 
== Introduction ==
== Use Case Basics ==

Use cases can be defined in many ways. There are many formal definitions for it. Very simply put, a use case is a reason to use a system. For example, a student borrowing a book from a library would be a use case of the library or a bank cardholder might need to use an ATM to get cash out of their account. More formally, “a use case is a collection of possible sequences of interactions between the system under discussion and its Users (or Actors), relating to a particular goal” [http://alistair.cockburn.us/Use+case+fundamentals].

A use case is initiated by a user with a particular goal in mind, and completes successfully when that goal is satisfied. The system is treated as a "black box", and the interactions with system, including system responses, are as perceived from outside the system.

Use cases capture who (actor) does what (interaction) with the system, for what purpose (goal), without dealing with system internals. A complete set of use cases specifies all the different ways to use the system, and therefore defines all behavior required of the system, bounding the scope of the system.[http://www.bredemeyer.com/use_cases.htm]

Now let us define some terms used with use cases: [http://en.wikipedia.org/wiki/Use_case]
<ol>
<li>Actor: An actor is a type of user that interacts with the system (ex student borrowing book or cardholder using ATM). Actors are also external entities (people or other systems) who interact with the system to achieve a desired goal. The goal must be of value to the actor.</li>

<li>Goal: Without a goal a use case is useless. There is no need for a use case when there is no need for any actor to achieve a goal. A goal briefly describes what the user intends to achieve with this use case. For example, the goal of a student using the library is to obtain the book. There is no point in having a use case like “the student enters the library” as that in itself has no value to the actor.</li>

<li>Stakeholder: A stakeholder is an individual or department that is affected by the outcome of the use case. Individuals are usually agents of the organization or department for which the use case is being created. A stakeholder might be called on to provide input, feedback, or authorization for the use case. The stakeholder section of the use case can include a brief description of which of these functions the stakeholder is assigned to fulfill.</li>
<li>Trigger: A trigger describes the event that causes the use case to be initiated. This event can be external or internal. If the trigger is not a simple true "event" (e.g., the customer presses a button), but instead "when a set of conditions are met", there will need to be a triggering process that continually (or periodically) runs to test whether the "trigger conditions" are met: the "triggering event" is a signal from the trigger process that the conditions are now met.
In our example with the student, a trigger would be the need for the book due to an approaching exam or test which causes the student to go to the library to borrow a book.
</li>

<li>Precondition: A precondition defines all the conditions that must be true (i.e., describes the state of the system) for the trigger to meaningfully cause the initiation of the use case. That is, if the system is not in the state described in the preconditions, the behavior of the use case is indeterminate. For example, the student should be a member of the library and have the required identity to borrow a book. If the student is not a member of the library, there is no point in the student trying to borrow a book from that library.</li>

<li>Scenarios: A scenario usually specifies when the use case starts and ends. It describes the interaction with actors and shows the flow of events between a user and system. For example, when a student tries to borrow a particular book from the library, it doesn’t always necessarily turn out the same way. Sometimes the book is available and sometimes it is already borrowed by someone else or the library may not have a given book. These are all examples of use case scenarios. The outcome in each case if different depending on circumstances, but they all relate to the same goal that is, they are all triggered by the same need(in this case, need for the book) and all the scenarios have the same starting point.</li>
</ol>

Now that we know something about use cases, let us go ahead and describe a simple use case:
Use Case 1: Request book from the library (automated system).

1.1: Summary/Goal
To borrow book a particular book from the library
1.2: Actors
Student
1.3: Preconditions
Student should be a member of the library and have an id.
1.4: Main Path
System requests for student ID and checks if he/she is a member
Student selects “request book”
Student enters name(s) of the book(s)
System checks for availability of books and displays results accordingly
Student confirms the order
System displays details of where the requested books are stacked
1.5: Alternate Path
System does not recognize Id or student is not a member. System will not allow any books to be checked out.
All books requested are already checked out. Displays this information to student and closes request.

The above description shows a very simple use case. However, there are a few essential characteristics to be noticed about the use case:
<ol>
<li>We have identified the key components of a use case, that is, the goal, actors, preconditions, key scenarios/flow and preconditions. It is very essential that we identify these components before writing a use case.</li>
<li>We have not gone into any sort of technical details about implementation or user interface design. Use cases only represent a very high level design. We are only trying to understand the flow and uses of the system.</li>
<li>We have recorded a set of paths (scenarios) that traverse an actor from a trigger event (start of the use case) to the goal (success scenarios).</li>
<li>We have recorded a set of scenarios that traverse an actor from a trigger event toward a goal but fall short of the goal (failure scenarios).</li>
</ol>

===Where can we use ‘use cases’?===

<ol>
<li>Use cases are usually used to capture the requirements of an interaction based system. When there is a lot of interaction between actors and the system, it makes sense to capture as many interactions and scenarios possible before starting development of the system.</li>
<li>Use cases help to eliminate rework due to requirements misunderstandings between developers and stakeholders by aiming to reach a point where there are no surprises for the users. Use cases help to build an explicit shared understanding that everyone can take away with them, the users, developers, testers, technical authors, and others.</li>
<li>Use cases have received some interest as a starting point for test design. By analyzing use cases for the system, we can know various interactions between the system and actors which will help in drawing out test plans.</li>
</ol>
===Where can’t we use ‘use cases’?===
[ http://en.wikipedia.org/wiki/Use_case]

<ol>
<li>Use case flows are not well suited to easily capturing non-interaction based requirements of a system (such as algorithm or mathematical requirements) or non-functional requirements (such as platform, performance, timing, or safety-critical aspects). These are better specified declaratively elsewhere.</li>
<li>Some systems are better described in an information/data-driven approach than in a functionality-driven approach of use cases. A good example of this kind of system is data-mining systems used for Business Intelligence. If you were to describe this kind of system in a use case model, it would be quite small and uninteresting (there are not many different functions here) but the set of data that the system handles may nevertheless be large and rich in details.</li>
</ol>

== Writing Use Cases ==
Writing Use Cases for a system is a process taken between those designing the system and the Stakeholders. There are many different ways to write Use Cases [SOURCE]. Because of this, there are many different formats that Use Cases can take when they are written. There are, however, certain guidelines that should be followed in the process of writing Use Cases. In general, these guidelines are:
<ol>
<li>Never include implementation specific terminology in the Use Case [SOURCE]</li>
<li>Each Use Case should be a set of scenarios, which include different flows of events [SOURCE]</li>
</ol>
=== Iterative Process ===
Normally, this process is done iteratively, so that the iterations can build upon each other [SOURCE]. Below is an example of three iterations of the Use Case writing process to illustrate how it can reveal things about a system and layout the functional requirements. 

For this example, we will be creating Use Cases to solve the following problem statement:

Develop a system to allow users to schedule meetings with each other.

In this system, the stakeholders will be the users of the system. The Users will also be the only Actors in the system. 

==== Iteration 1 ====
For the first iteration, we will write out short sentences to describe the functionality that the system will have. Some use cases could be:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>1</td>
<td>Request a Meeting</td>
<td>User</td>
</tr>
<tr>
<td>2</td>
<td>Approve a meeting request</td>
<td>User</td>
</tr>
<tr>
<td>3</td>
<td>Suggest a new time</td>
<td>User</td>
</tr>
<tr>
<td>4</td>
<td>View a User's schedule</td>
<td>User</td>
</tr>
</table>

In this example, the fourth Use Case may not have been an obvious requirement that could be derived from the original problem statement, but in the process of creating the Use Cases, it was discovered that it would be a good requirement for the system to have.

==== Iteration 2 ====

The next iteration would involve writing out longer descriptions for each. This could be done in paragraph form, or by writing a list. Below are the Use Cases in paragraph form:

'''Use Case 1 – Request a meeting'''
User A chooses the date and time for a meeting with User B. User A chooses User B as the recipient of the meeting request.
User A sends the meeting request to User B through the system. 
'''Use Case 2 – Approve a Meeting Request'''
User A receives a meeting request from User B and accepts the user request. A notification that User A has accepted the meeting is sent to User B. 
'''Use Case 3 – Suggest a different meeting time'''
User A receives a meeting request from User B and suggests a different time and/or date for the meeting. The response is sent to User B through
the system. 
'''Use Case 4 – View a User's schedule'''
User A would like to schedule a meeting with User B. User A starts the system and opens up User B's schedule.
User A can see when User B has already scheduled meetings and User A can then use that information to send User B a meeting request.
Use A can also access their own schedule to view when User A has scheduled meetings. 

From writing out the Use Cases with more description, it should become clear that Use Case 2 and Use Case 3 are very similar. In both Use Cases, User A responds to a meeting request and a response/notification is sent to User B. This might lead the designers of the system to combine these two Use Cases into one Use Case for "Respond to Request."

==== Iteration 3 ====

In the next iteration, we're going to use a Use Case template. There are many different Use Case templates, which include different information [SOURCES]. A template can be created that is unique for the system being described, provided each Use Case uses the same template. The template we will use will include:

Use Case <Number>: Title 
<Number>.1: <Summary/Goal> 
<Number>.2: <Actors> 
<Number>.3: <Preconditions> 
<Number>.4: <Main Path> 
<Number>.5: <Alternate Paths – including sub-flows [S] and error-flows [E]> 

Writing Use Case 1 in this format yields:

Use Case 1: Request a meeting 
1.1: Summary/Goal
User A can choose the date and time for a meeting with User B [Main]. User A can choose User B as the recipient of the meeting
request [Main], or multiple Users as the recipient [S.2]. User A sends the meeting request to User B through the system [Main].
Before User A sends the meeting request, User A can opt not to send the request and delete it [S.1]. If User B is no longer in
the system, User A receives notification that the meeting request cannot be sent [E.1]. 
1.2: Actors
Users 
1.3: Preconditions
- User A and User B are recorded as Users in the system
- User A has logged into the system 
1.4: Main Path
1) User A chooses a date for a meeting
2) User A chooses a time for a meeting
3) User A chooses User B as the recipient for the meeting request
4) User A submits the meeting request
5) User B receives the meeting request the next time User B logs into the system 
1.5: Alternative Path
S.1
User A creates a meeting request, but down not submit it. A meeting request is not sent to User B 
S.2
User A creates a meeting request for more than one User. User A submits the meeting request and each User receives it the next
time they log in 
E.1
User B is no longer a User in the system. User A receives notification that the meeting request cannot be sent. 

==== Results ====
There are a few interesting things revealed about the system by re-writing the Use Case in this format. The most important is likely that Users will need to "log-in" to the system. This implies that there could be another Actor in the system, namely an Admin. This leads to these additional Use Cases:
<table border=1>
<tr>
<td>Use Case #</td>
<td>Description</td>
<td>Actor</td>
</tr>
<tr>
<td>5</td>
<td>Log into the system</td>
<td>User</td>
</tr>
<tr>
<td>6</td>
<td>Create a User in the system</td>
<td>Admin</td>
</tr>
</table>

Each of these new Use Cases would then go through the iterations listed above until they are in the template form. 

As you can see from the example, each iteration refines the Use Case and helps to clarify the requirements of the system.

== Use Case Diagrams ==

Use Case Diagrams are useful for showing how each component in a system will interact with other components of the system [SOURCE]. They are not good for showing the flow of events that a system will have, like the written Use Cases are [SOURCE]. Also, unlike written Use Cases, Use Case Diagrams use UML so that there is a standard.

DEFINE UML HERE

=== Components of a Use Case Diagram ===

UCDs have only 4 major elements: The actors that the system you are describing interacts with, the system itself, the use cases, or services, that the system knows how to perform, and the lines that represent relationships between these elements.[SOURCE: http://www.andrew.cmu.edu/course/90-754/umlucdfaq.html#uses – DIRECT QUOTE]

'''Actors''' in Use Case Diagrams are represented by stick figures:

[[Image:Actor.png]]

'''Use Cases''' are represented by ovals:

[[Image:UseCase.png]]

'''Relationships''' are represented by Solid Lines. Sometimes, arrowheads are added to the lines to indicate the direction of the invocation, or to show which actor is the primary actor [SOURCE: http://www.agilemodeling.com/artifacts/useCaseDiagram.htm]

[[Image:Lines.png]]

Two special relationships that can be shown in a Use Case Diagram are the ''Extends'' and ''Includes'' relationships. These relationships are usually shown with a dotted line with an arrowhead and <<extend>> or <<include>> written near the line.

The ''Extends'' relationship is used to show when Use Case X is a special case of Use Case Y [SOURCE]. In this situation, the dotted line is drawn from Use Case X to Use Case Y with the arrowhead pointing to Use Case Y.

The ''Includes/Uses'' relationship is used to show that every time Use Case X is done, Use Case Y must also be done [SOURCE]. In this case, the arrow points to Use Case Y.

=== Creating a Use Case Diagram ===

A Use Case Diagram for the same system described in the Writing a Use Case might look something like:

[[Image:UCDiagram.png]]

As you can see, "Accept Meeting" and "Suggest new time" are special cases of "Respond to request". Also, from this diagram, the system designers are saying that in order to "Request a Meeting" the user must "View Schedule".

== Advanced Topics ==
== Tools and Examples ==

=== Tools ===

There are many different tools available to create Use Cases. For a more comprehensive list, go to [http://en.wikipedia.org/wiki/List_of_Unified_Modeling_Language_tools Wikipedia's list of UML modeling tools]. A sampling are below: 
<ul>
<li>'''Rational Rose:'''

One of the most popular tool for use-case driven development.

http://www-306.ibm.com/software/awdtools/developer/rose/index.html</li>

<li>'''Sun Java Studio Enterprise:'''

Sun Java Studio Enterprise offers a UML tool.

http://developers.sun.com/jsenterprise/</li>

<li>'''Visual case:'''

UML & E/R Database Design Tool

http://www.visualcase.com/</li>

</ul>

=== Examples ===
There are many different examples of Use Cases. Some are listed below: 
<ul>
<li> http://www.objectmentor.com/resources/articles/usecases.pdf </li>
<li> http://www.w3.org/2002/06/ws-example </li>
<li> http://www.agilemodeling.com/essays/useCaseReuse.htm </li>
<li> http://www.soi.wide.ad.jp/class/20040034/slides/07/9.html </li>
<li> http://www.cs.colorado.edu/~kena/classes/6448/s05/reference/usecases/examples.html </li>
<li> http://courses.softlab.ntua.gr/softeng/Tutorials/UML-Use-Cases.pdf </li>
</ul>
== Further Reading ==

== References ==

CSC/ECE 517 Fall 2010/ch4 4a RJ

2010-10-20T04:06:37Z

Bazinga: /* Use Case Basics */