Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2013/oss E811 syn

2013-11-07T20:26:39Z

Hsure: /* Testing */

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication<ref>http://en.wikipedia.org/wiki/Duplicate_code</ref> is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse<ref>http://voices.yahoo.com/programming-code-reusability-11278802.html</ref>.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods<ref>http://sourcemaking.com/refactoring/long-method</ref> are often caused due to unnecessary parameters. Long list of parameters reduce readability<ref>http://simpleprogrammer.com/2013/04/14/what-makes-code-readable-not-what-you-think/</ref> of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell<ref>http://www.codinghorror.com/blog/2006/05/code-smells.html</ref> ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code'''<ref>http://en.wikipedia.org/wiki/Dead_code</ref>: Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Testing==

To verify that the changes didn't break anything. One can login to the VCL instance using username/password: sample/sample. One can go to your work page in an assignment. Upload a hyperlink and delete it.

==Future Work==

*Polymorphism<ref>http://en.wikipedia.org/wiki/Polymorphism_(computer_science)</ref> can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2013/oss E811 syn

2013-11-07T20:25:20Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication<ref>http://en.wikipedia.org/wiki/Duplicate_code</ref> is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse<ref>http://voices.yahoo.com/programming-code-reusability-11278802.html</ref>.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods<ref>http://sourcemaking.com/refactoring/long-method</ref> are often caused due to unnecessary parameters. Long list of parameters reduce readability<ref>http://simpleprogrammer.com/2013/04/14/what-makes-code-readable-not-what-you-think/</ref> of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell<ref>http://www.codinghorror.com/blog/2006/05/code-smells.html</ref> ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code'''<ref>http://en.wikipedia.org/wiki/Dead_code</ref>: Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Testing==

To verify that the changes didn't break anything. One can login to the VCL instance using username/password: sample/sample. One can upload a hyperlink and delete it.

==Future Work==

*Polymorphism<ref>http://en.wikipedia.org/wiki/Polymorphism_(computer_science)</ref> can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T22:50:33Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication<ref>http://en.wikipedia.org/wiki/Duplicate_code</ref> is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse<ref>http://voices.yahoo.com/programming-code-reusability-11278802.html</ref>.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods<ref>http://sourcemaking.com/refactoring/long-method</ref> are often caused due to unnecessary parameters. Long list of parameters reduce readability<ref>http://simpleprogrammer.com/2013/04/14/what-makes-code-readable-not-what-you-think/</ref> of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell<ref>http://www.codinghorror.com/blog/2006/05/code-smells.html</ref> ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code'''<ref>http://en.wikipedia.org/wiki/Dead_code</ref>: Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism<ref>http://en.wikipedia.org/wiki/Polymorphism_(computer_science)</ref> can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T22:50:03Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication<ref>http://en.wikipedia.org/wiki/Duplicate_code</ref> is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse<ref>http://voices.yahoo.com/programming-code-reusability-11278802.html</ref>.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods<ref>http://sourcemaking.com/refactoring/long-method</ref> are often caused due to unnecessary parameters. Long list of parameters reduce readability<ref>http://simpleprogrammer.com/2013/04/14/what-makes-code-readable-not-what-you-think/</ref> of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell<ref>http://www.codinghorror.com/blog/2006/05/code-smells.html</ref> ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code'''<ref>http://en.wikipedia.org/wiki/Dead_code</ref>: Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism<ref>http://en.wikipedia.org/wiki/Polymorphism_(computer_science)</ref> can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''See Also''' ==
*http://www.codinghorror.com/blog/2006/05/code-smells.html

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T22:19:09Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code<ref>http://en.wikipedia.org/wiki/Duplicate_code</ref>. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods<ref>http://sourcemaking.com/refactoring/long-method</ref> are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell<ref>http://www.codinghorror.com/blog/2006/05/code-smells.html</ref> ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''See Also''' ==
*http://www.codinghorror.com/blog/2006/05/code-smells.html

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T22:16:25Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods<ref>http://sourcemaking.com/refactoring/long-method</ref> are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell<ref>http://www.codinghorror.com/blog/2006/05/code-smells.html</ref> ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''See Also''' ==
*http://www.codinghorror.com/blog/2006/05/code-smells.html

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T22:14:36Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell<ref>http://www.codinghorror.com/blog/2006/05/code-smells.html</ref> ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*http://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*http://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T21:59:23Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*http://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*http://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T21:58:21Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample
 

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*http://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*http://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T21:54:32Z

Hsure:

== '''Refactor & test submitted_content_controller & submitted_content_helper''' ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T21:53:58Z

Hsure:

==Refactor & test submitted_content_controller & submitted_content_helper ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T21:53:19Z

Hsure:

==Refactor & test submitted_content_controller & submitted_content_helper ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 

__TOC__

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T21:53:01Z

Hsure:

==Refactor & test submitted_content_controller & submitted_content_helper ==
Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 

__TOC__

== '''Introduction''' ==

== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T21:38:15Z

Hsure:

==Refactor & test submitted_content_controller & submitted_content_helper ==

 

__TOC__

== '''Introduction''' ==

Expertiza is a web application that is used for Project/Assignment submissions. Students can form teams, select topics, submit assignments, review other's work and give feedback for reviews. Submission of work can be done in two ways:
*Hyperlinks
*Files/Folders

Submitted_Content_Controller and Submitted_Content_Helper are designed to handle operations on hyperlinks and files. They include methods to submit, verify and remove hyperlinks; and create, move, rename, submit and remove files.
 
== '''Project Description''' ==

Classes: submitted_content_controller.rb (250 lines) 
submitted_content_helper.rb (98 lines) 
What they do: Allow users to submit files and links to Expertiza. 
What needs to be done: The methods are long and complex, and contain a lot of duplicated code. In particular, there are two different ways of submitting files: as a homework submission, and uploading a review file requested by a review rubric. These should use common code as much as possible. The approach to deleting submitted links and submitted files should be analogous. There have been bugs in deleting hyperlinks, so be sure to test the code thoroughly.
 
== '''Design Changes''' ==

*Code duplication is generally considered a mark of poor or lazy programming style. Good coding style is generally associated with code reuse.

:We identified a sequence of operations that are repetitively used in methods which are used to submit files for the first time and again in review. The code to check if a file exists or not and creating a new directory path for any new submission is common for both submission and review pages. Thus we separated it out as a different method ‘check_file_exists’ as shown below:

<pre>
def check_file_exists curr_directory
#check if file exists. If not, create a new file. Else, remove the existing file and then create new file.
if !File.exists? curr_directory
FileUtils.mkdir_p(curr_directory)
else
FileUtils.rm_rf(curr_directory)
FileUtils.mkdir_p(curr_directory)
end
end
</pre>

This method can now be called from both submit_file and custom_submit_file.

<pre>
def submit_file
participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(participant.user_id)

file = params[:uploaded_file]
participant.set_student_directory_num

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end

curr_directory = participant.get_path.to_s+@current_folder.name
check_file_exists(curr_directory)

safe_filename = file.original_filename.gsub(/\\/,"/")
safe_filename = FileHelper::sanitize_filename(safe_filename) # new code to sanitize file path before upload*
full_filename = curr_directory + File.split(safe_filename).last.gsub(" ",'_') #safe_filename #curr_directory +
File.open(full_filename, "wb") { |f| f.write(file.read) }

if params['unzip']
SubmittedContentHelper::unzip_file(full_filename, curr_directory, true) if get_file_type(safe_filename) == "zip"
end
participant.update_resubmit_times

#send message to reviewers when submission has been updated
participant.assignment.email(participant.id) rescue nil # If the user has no team: 1) there are no reviewers to notify; 2) calling email will throw an exception. So rescue and ignore it.

redirect_to :action => 'edit', :id => participant.id
end
</pre>
 
*Long methods are often caused due to unnecessary parameters. Long list of parameters reduce readability of code. Following changes are made to remove such unnecessary parameters:

[[File:Unzip file.JPG|frame|none|alt=Before Refactoring|Before Refactoring]]

Here the variable safename is declared and used only once. The assignment can be made inline by replacing it in the method call with actual logic in the below way:

[[File:Unzip file mod.JPG|frame|none|alt=After Refactoring|After Refactoring]]
 
*Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

[[File:Fpath.png|frame|none|alt=Before Refactoring|Before Refactoring]] [[File:Filepath.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Consecutive assignments or modifications of the same variable can lead to “Long method” or “Excessive use of literals”. Such code smells are removed. For example, variable ‘newloc’ which is modified consecutively is refactored in the following way:

:Before Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_loc = @participant.get_path
new_loc+= "/"
new_loc+= params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_loc)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

:After Refactoring:
<pre>
def move_selected_file
old_filename = params[:directories][params[:chk_files]] + "/" + params[:filenames][params[:chk_files]]
new_location = @participant.get_path + "/" + params[:faction][:move]
begin
FileHelper::move_file(old_filename, new_location)
flash[:note] = "The file was moved successfully from \"/#{params[:filenames][params[:chk_files]]}\" to \"/#{params[:faction][:move]}\""
rescue
flash[:error] = "There was a problem moving the file: "+$!
end
end
</pre>

Modified code reduces the method length and increases Readability.
 
*Unnecessary variable declarations which are never used in the method increase the length of code and confuse the readers. For example, the variable ‘display’ shown in the code snippet below was defined but never used in the method. Such variables can be removed.

[[File:Display variable.png|frame|none|alt=Before Refactoring|Before Refactoring]]

The actual variable that was used which is ‘disp’ can now be renamed to ‘display’ which is more meaningful.

[[File:Display change.png|frame|none|alt=After Refactoring|After Refactoring]]
 
*Many more minor code changes are made following the Ruby Coding guidelines. For example:

<pre>
if !File.exist?(new_filename)
</pre>

We should prefer to use 'unless' for such conditions:

<pre>
unless File.exist?(new_filename)
</pre>
 
== List of Code Smells identified and removed ==
*'''Duplicated code''': Identical or very similar code exists in more than one location. Code duplication frequently creates long, repeated sections of code that differ in only a few lines or characters. The length of such routines can make it difficult to quickly understand them. The repetition of largely identical code sections can conceal how they differ from one another, and therefore, what the specific purpose of each code section is. Often, the only difference is in a parameter value. The best practice in such cases is a reusable subroutine.
*'''Long method''': A method, function, or procedure that has grown too large. Since the early days of programming people have realized that the longer a procedure is, the more difficult it is to understand. Older languages carried an overhead in subroutine calls, which deterred people from small methods. Modern OO languages have pretty much eliminated that overhead for in-process calls.
*'''Too many parameters''': A long list of parameters in a procedure or function make readability and code quality worse. The more parameters a method has, the more complex it is. Limit the number of parameters you need in a given method, or use an object to combine the parameters.
*'''Excessively long identifiers''': In particular, the use of naming conventions to provide disambiguation that should be implicit in the software architecture.
*'''Excessively short identifiers''': The name of a variable should reflect its function unless the function is obvious. Pick a set of standard terminology and stick to it throughout your methods. For example, if you have Open(), you should probably have Close().
*'''Excessive use of literals''': These should be coded as named constants, to improve readability and to avoid programming errors. Additionally, literals can and should be externalized into resource files/scripts where possible, to facilitate localization of software if it is intended to be deployed in different regions.
*'''Complex conditionals''': Branches that check lots of unrelated conditions and edge cases that don't seem to capture the meaning of a block of code. Large conditional logic blocks, particularly blocks that tend to grow larger or change significantly over time have to be eliminated. Consider alternative object-oriented approaches such as decorator, strategy, or state.
*'''Dead Code''': Ruthlessly delete code that isn't being used. Unused code will result in Long classes or long methods.
 

==Future Work==

*Polymorphism can be implemented by pushing some methods to relevant classes. Following section of code contains certain method calls which are implemented in the same class. These can be abstracted into a different class for file operations:

<pre>
def file_folder_action
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

@current_folder = DisplayOption.new
@current_folder.name = "/"
if params[:current_folder]
@current_folder.name = FileHelper::sanitize_folder(params[:current_folder][:name])
end
if params[:faction][:delete] #call method to delete selected files
delete_selected_files
elsif params[:faction][:rename] #call method to rename selected files
rename_selected_file
elsif params[:faction][:move] #call method to move selected files
move_selected_file
elsif params[:faction][:copy] #call method to copy selected files
copy_selected_file
elsif params[:faction][:create] #call method to create new folder
create_new_folder
end

redirect_to :action => 'edit', :id => @participant.id
end
</pre>

*Submit file functionality currently breaks with the latest expertiza master branch code which can be fixed by further exploration.
*Design changes made in partial files can be extended such that code reuse can be maximized.
*Many more code smells can be identified and removed to improve elegance.
*RSpec test cases for the changes made can be added.

==Appendix: setup issues==

Steps to setup the project:
*Extract source code in RubyMine using the following url: https://github.com/hsure/expertiza
:(A) VCS -> Checkout from version control -> Github
:(B) Give this url: https://github.com/hsure/expertiza -> Finish
*Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
*Run bundle install
*Run - rake db:create:all
*Run - rake db:migrate
*From the Expertiza folder (project root) execute the command “rails server”
 
You should be able to view the test Database in MySQL.
 
Use the following credentials to explore the application:
 
Username: admin (Administrator)
 
Password: admin
 
Username: sample (User)
 
Password: sample

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-24T20:24:46Z

Hsure:

== '''Ruby Coding Guidelines''' ==

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the [http://en.wikipedia.org/wiki/Category:Object-oriented_programming_languages object oriented programming languages] as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on [http://en.wikipedia.org/wiki/Unix UNIX]-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than [http://en.wikipedia.org/wiki/CamelCase camelBack] for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of [http://en.wikipedia.org/wiki/Mixin mix-ins] (which are just modules), however, should probably be adjectives, such as the standard [http://en.wikibooks.org/wiki/Ruby_Programming/Reference/Objects/Enumerable Enumerable] and [http://www.ruby-doc.org/core-2.0.0/Comparable.html Comparable] modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''[http://en.wikipedia.org/wiki/Visitor_pattern The Visitor pattern]''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''[http://en.wikipedia.org/wiki/Delegation_pattern Delegation]''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''[http://en.wikipedia.org/wiki/Singleton_pattern Singleton pattern]''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''[http://en.wikipedia.org/wiki/Observer_pattern Observer pattern]''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
<pre>
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”
</pre>

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

<pre>
header block with author's name, Perforce Id tag and a brief description of what the program or library is for.
require statements
include statements
class and module definitions
main program section
</pre>

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.ruby-toolbox.com/categories/code_metrics</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[http://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[http://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[http://saikuro.rubyforge.org/ '''Saikuro'''] - designed to check cyclomatic complexity
*[http://ruby.sadi.st/Flog.html '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[http://ruby.sadi.st/Flay.html '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*http://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*http://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-24T20:22:15Z

Hsure: /* Code Analysis Tools */

== '''Ruby Coding Guidelines''' ==

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the [http://en.wikipedia.org/wiki/Category:Object-oriented_programming_languages object oriented programming languages] as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on [http://en.wikipedia.org/wiki/Unix UNIX]-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than [http://en.wikipedia.org/wiki/CamelCase camelBack] for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of [http://en.wikipedia.org/wiki/Mixin mix-ins] (which are just modules), however, should probably be adjectives, such as the standard [http://en.wikibooks.org/wiki/Ruby_Programming/Reference/Objects/Enumerable Enumerable] and [http://www.ruby-doc.org/core-2.0.0/Comparable.html Comparable] modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''[http://en.wikipedia.org/wiki/Visitor_pattern The Visitor pattern]''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''[http://en.wikipedia.org/wiki/Delegation_pattern Delegation]''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''[http://en.wikipedia.org/wiki/Singleton_pattern Singleton pattern]''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''[http://en.wikipedia.org/wiki/Observer_pattern Observer pattern]''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
<pre>
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”
</pre>

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

<pre>
header block with author's name, Perforce Id tag and a brief description of what the program or library is for.
require statements
include statements
class and module definitions
main program section
</pre>

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>https://www.ruby-toolbox.com/categories/code_metrics</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[http://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[http://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[http://saikuro.rubyforge.org/ '''Saikuro'''] - designed to check cyclomatic complexity
*[http://ruby.sadi.st/Flog.html '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[http://ruby.sadi.st/Flay.html '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*http://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*http://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-24T20:20:23Z

Hsure: /* Code Analysis Tools */

== '''Ruby Coding Guidelines''' ==

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the [http://en.wikipedia.org/wiki/Category:Object-oriented_programming_languages object oriented programming languages] as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on [http://en.wikipedia.org/wiki/Unix UNIX]-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than [http://en.wikipedia.org/wiki/CamelCase camelBack] for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of [http://en.wikipedia.org/wiki/Mixin mix-ins] (which are just modules), however, should probably be adjectives, such as the standard [http://en.wikibooks.org/wiki/Ruby_Programming/Reference/Objects/Enumerable Enumerable] and [http://www.ruby-doc.org/core-2.0.0/Comparable.html Comparable] modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''[http://en.wikipedia.org/wiki/Visitor_pattern The Visitor pattern]''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''[http://en.wikipedia.org/wiki/Delegation_pattern Delegation]''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''[http://en.wikipedia.org/wiki/Singleton_pattern Singleton pattern]''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''[http://en.wikipedia.org/wiki/Observer_pattern Observer pattern]''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
<pre>
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”
</pre>

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

<pre>
header block with author's name, Perforce Id tag and a brief description of what the program or library is for.
require statements
include statements
class and module definitions
main program section
</pre>

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>https://www.ruby-toolbox.com/categories/code_metrics</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[http://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[http://https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[http://saikuro.rubyforge.org/ '''Saikuro'''] - designed to check cyclomatic complexity
*[http://http://ruby.sadi.st/Flog.html '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[http://ruby.sadi.st/Flay.html '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*http://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*http://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-24T20:15:57Z

Hsure: /* Code Analysis Tools */

== '''Ruby Coding Guidelines''' ==

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the [http://en.wikipedia.org/wiki/Category:Object-oriented_programming_languages object oriented programming languages] as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on [http://en.wikipedia.org/wiki/Unix UNIX]-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than [http://en.wikipedia.org/wiki/CamelCase camelBack] for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of [http://en.wikipedia.org/wiki/Mixin mix-ins] (which are just modules), however, should probably be adjectives, such as the standard [http://en.wikibooks.org/wiki/Ruby_Programming/Reference/Objects/Enumerable Enumerable] and [http://www.ruby-doc.org/core-2.0.0/Comparable.html Comparable] modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''[http://en.wikipedia.org/wiki/Visitor_pattern The Visitor pattern]''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''[http://en.wikipedia.org/wiki/Delegation_pattern Delegation]''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''[http://en.wikipedia.org/wiki/Singleton_pattern Singleton pattern]''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''[http://en.wikipedia.org/wiki/Observer_pattern Observer pattern]''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
<pre>
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”
</pre>

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

<pre>
header block with author's name, Perforce Id tag and a brief description of what the program or library is for.
require statements
include statements
class and module definitions
main program section
</pre>

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>https://www.ruby-toolbox.com/categories/code_metrics</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[http://www.ruby-toolbox.com/categories/code_metrics '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[http://www.ruby-toolbox.com/categories/code_metrics '''Reek'''] - similar in concept to Roodi
*[http://www.ruby-toolbox.com/categories/code_metrics '''Saikuro'''] - designed to check cyclomatic complexity
*[http://www.ruby-toolbox.com/categories/code_metrics '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[http://www.ruby-toolbox.com/categories/code_metrics '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*http://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*http://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-24T05:08:36Z

Hsure: /* Ruby Coding Guidelines */

== '''Ruby Coding Guidelines''' ==

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the [http://en.wikipedia.org/wiki/Category:Object-oriented_programming_languages object oriented programming languages] as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on [http://en.wikipedia.org/wiki/Unix UNIX]-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than [http://en.wikipedia.org/wiki/CamelCase camelBack] for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of [http://en.wikipedia.org/wiki/Mixin mix-ins] (which are just modules), however, should probably be adjectives, such as the standard [http://en.wikibooks.org/wiki/Ruby_Programming/Reference/Objects/Enumerable Enumerable] and [http://www.ruby-doc.org/core-2.0.0/Comparable.html Comparable] modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''[http://en.wikipedia.org/wiki/Visitor_pattern The Visitor pattern]''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''[http://en.wikipedia.org/wiki/Delegation_pattern Delegation]''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''[http://en.wikipedia.org/wiki/Singleton_pattern Singleton pattern]''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''[http://en.wikipedia.org/wiki/Observer_pattern Observer pattern]''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
<pre>
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”
</pre>

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

<pre>
header block with author's name, Perforce Id tag and a brief description of what the program or library is for.
require statements
include statements
class and module definitions
main program section
</pre>

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>https://www.ruby-toolbox.com/categories/code_metrics</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://www.ruby-toolbox.com/categories/code_metrics '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek/wiki '''Reek'''] - similar in concept to Roodi
*[https://www.ruby-toolbox.com/categories/code_metrics '''Saikuro'''] - designed to check cyclomatic complexity
*[https://www.ruby-toolbox.com/categories/code_metrics '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://www.ruby-toolbox.com/categories/code_metrics '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*https://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*https://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-24T05:08:18Z

Hsure: /* Ruby Coding Guidelines */

== '''Ruby Coding Guidelines''' ==

div#content a[href ^="https://"].external
background: center right no-repeat; padding-right: 18px;
/div

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the [http://en.wikipedia.org/wiki/Category:Object-oriented_programming_languages object oriented programming languages] as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on [http://en.wikipedia.org/wiki/Unix UNIX]-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than [http://en.wikipedia.org/wiki/CamelCase camelBack] for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of [http://en.wikipedia.org/wiki/Mixin mix-ins] (which are just modules), however, should probably be adjectives, such as the standard [http://en.wikibooks.org/wiki/Ruby_Programming/Reference/Objects/Enumerable Enumerable] and [http://www.ruby-doc.org/core-2.0.0/Comparable.html Comparable] modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''[http://en.wikipedia.org/wiki/Visitor_pattern The Visitor pattern]''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''[http://en.wikipedia.org/wiki/Delegation_pattern Delegation]''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''[http://en.wikipedia.org/wiki/Singleton_pattern Singleton pattern]''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''[http://en.wikipedia.org/wiki/Observer_pattern Observer pattern]''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
<pre>
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”
</pre>

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

<pre>
header block with author's name, Perforce Id tag and a brief description of what the program or library is for.
require statements
include statements
class and module definitions
main program section
</pre>

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>https://www.ruby-toolbox.com/categories/code_metrics</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://www.ruby-toolbox.com/categories/code_metrics '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek/wiki '''Reek'''] - similar in concept to Roodi
*[https://www.ruby-toolbox.com/categories/code_metrics '''Saikuro'''] - designed to check cyclomatic complexity
*[https://www.ruby-toolbox.com/categories/code_metrics '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://www.ruby-toolbox.com/categories/code_metrics '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*https://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*https://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-24T05:07:49Z

Hsure:

== '''Ruby Coding Guidelines''' ==

[[div#content a[href ^="https://"].external]]
background: center right no-repeat; padding-right: 18px;
[[/div]]

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the [http://en.wikipedia.org/wiki/Category:Object-oriented_programming_languages object oriented programming languages] as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on [http://en.wikipedia.org/wiki/Unix UNIX]-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than [http://en.wikipedia.org/wiki/CamelCase camelBack] for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of [http://en.wikipedia.org/wiki/Mixin mix-ins] (which are just modules), however, should probably be adjectives, such as the standard [http://en.wikibooks.org/wiki/Ruby_Programming/Reference/Objects/Enumerable Enumerable] and [http://www.ruby-doc.org/core-2.0.0/Comparable.html Comparable] modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''[http://en.wikipedia.org/wiki/Visitor_pattern The Visitor pattern]''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''[http://en.wikipedia.org/wiki/Delegation_pattern Delegation]''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''[http://en.wikipedia.org/wiki/Singleton_pattern Singleton pattern]''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''[http://en.wikipedia.org/wiki/Observer_pattern Observer pattern]''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
<pre>
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”
</pre>

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

<pre>
header block with author's name, Perforce Id tag and a brief description of what the program or library is for.
require statements
include statements
class and module definitions
main program section
</pre>

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>https://www.ruby-toolbox.com/categories/code_metrics</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://www.ruby-toolbox.com/categories/code_metrics '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek/wiki '''Reek'''] - similar in concept to Roodi
*[https://www.ruby-toolbox.com/categories/code_metrics '''Saikuro'''] - designed to check cyclomatic complexity
*[https://www.ruby-toolbox.com/categories/code_metrics '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://www.ruby-toolbox.com/categories/code_metrics '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*https://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*https://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-23T21:28:26Z

Hsure:

== '''Ruby Coding Guidelines''' ==

[[div#content a[href ^="https://"].external]]
background: center right no-repeat; padding-right: 18px;
[[/div]

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the [http://en.wikipedia.org/wiki/Category:Object-oriented_programming_languages object oriented programming languages] as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on [http://en.wikipedia.org/wiki/Unix UNIX]-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than [http://en.wikipedia.org/wiki/CamelCase camelBack] for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of [http://en.wikipedia.org/wiki/Mixin mix-ins] (which are just modules), however, should probably be adjectives, such as the standard [http://en.wikibooks.org/wiki/Ruby_Programming/Reference/Objects/Enumerable Enumerable] and [http://www.ruby-doc.org/core-2.0.0/Comparable.html Comparable] modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''[http://en.wikipedia.org/wiki/Visitor_pattern The Visitor pattern]''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''[http://en.wikipedia.org/wiki/Delegation_pattern Delegation]''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''[http://en.wikipedia.org/wiki/Singleton_pattern Singleton pattern]''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''[http://en.wikipedia.org/wiki/Observer_pattern Observer pattern]''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
<pre>
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”
</pre>

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

<pre>
header block with author's name, Perforce Id tag and a brief description of what the program or library is for.
require statements
include statements
class and module definitions
main program section
</pre>

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>https://www.ruby-toolbox.com/categories/code_metrics</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://www.ruby-toolbox.com/categories/code_metrics '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek/wiki '''Reek'''] - similar in concept to Roodi
*[https://www.ruby-toolbox.com/categories/code_metrics '''Saikuro'''] - designed to check cyclomatic complexity
*[https://www.ruby-toolbox.com/categories/code_metrics '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://www.ruby-toolbox.com/categories/code_metrics '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml
*https://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*https://www.ruby-lang.org/en/documentation/
*http://en.wikibooks.org/wiki/Ruby_programming_language

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:54:33Z

Hsure: /* Ruby Coding Guidelines */

== '''Ruby Coding Guidelines''' ==

[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby] Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.infoq.com/news/2009/09/code-quality-metric-fu</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:53:48Z

Hsure: /* Ruby Coding Guidelines */

== '''Ruby Coding Guidelines''' ==

[[http://en.wikipedia.org/wiki/Ruby_(programming_language) Ruby]] Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.infoq.com/news/2009/09/code-quality-metric-fu</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:51:10Z

Hsure: /* Performance Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines<ref>http://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/</ref> ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.infoq.com/news/2009/09/code-quality-metric-fu</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:46:32Z

Hsure: /* Layout Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines<ref>http://www.caliban.org/ruby/rubyguide.shtml</ref> ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.infoq.com/news/2009/09/code-quality-metric-fu</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:45:28Z

Hsure: /* Documentation Guidelineshttp://guides.rubyonrails.org/api_documentation_guidelines.html */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref> can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.infoq.com/news/2009/09/code-quality-metric-fu</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:44:35Z

Hsure: /* Documentation Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines<ref>http://guides.rubyonrails.org/api_documentation_guidelines.html</ref> ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref>

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.infoq.com/news/2009/09/code-quality-metric-fu</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:42:23Z

Hsure: /* Naming Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines<ref>http://itsignals.cascadia.com.au/?p=7</ref> ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref>

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.infoq.com/news/2009/09/code-quality-metric-fu</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:40:55Z

Hsure: /* Code Analysis Tools */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref>

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools<ref>http://www.infoq.com/news/2009/09/code-quality-metric-fu</ref> can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:38:07Z

Hsure: /* Documentation Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.<ref>http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html</ref>

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:36:52Z

Hsure: /* Performance Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:36:18Z

Hsure: /* Performance Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages<ref/>

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-18T17:35:10Z

Hsure: /* References */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
<references/>

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-17T23:21:34Z

Hsure: /* Performance Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Concatenated strings calls a method to get executed. So, it affects the performance as it is one of the most frequently used operation. Its better to replace them with Interpolated strings which runs faster as it doesn't invoke a method call.
put “Hello there, #{name}!”vs.puts “Hello there, ” << name = “!”

*'''Destructive operations are faster'''
: Ruby’s in-place methods that which modifies the actual value than working on a copy of the data are much faster. But this should be handled carefully as original data gets disturbed.

*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.

*'''For loops are faster than .each'''
: .each uses an enumeration object behind the scene which adds a delay in execution. Using for instead of .each would improve performance but for short loops only.

*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.

*'''Avoid calls to parse_date and strftime'''
: Both these calls are very expensive. using regular expressions would improve the time.

*'''Know your gems'''
: All libraries are not efficient. Many gems may need to be removed to problem to fix a problem with the code. This is a common scenario when many gems are installed. So performing bench marking and testing a gem with others that perform same task would help in picking the right gem.

*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements results in evident improvements in performance of the code. It is always ideal to design an efficient algorithm without unwanted method calls.

*'''Test the most frequently occurring case first'''
: While using if statements or a case statement always test the cases that occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.

*'''Optimize the way you access global constants'''
: While accessing the global constants one should use namespace before the constants to avoid entire library search for the constant.

*'''Use explicit returns'''
: Even though the result of last operation is returned for a method, using explicit returns would speed up the code. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
*http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html
*http://www.infoq.com/news/2009/09/code-quality-metric-fu
*http://itsignals.cascadia.com.au/?p=7
*http://guides.rubyonrails.org/api_documentation_guidelines.html
*http://www.caliban.org/ruby/rubyguide.shtml
*http://en.wikipedia.org/wiki/Ruby_(programming_language)
*http://graidengarrison.weebly.com/1/post/2013/03/the-importance-of-coding-standards-in-net-development.html
*http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-17T21:55:19Z

Hsure:

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*'''Destructive operations are faster'''
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*'''For loops are faster than .each'''
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*'''Avoid calls to parse_date and strftime'''
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*'''Don’t use unnecessary block parameters'''
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*'''Know your gems'''
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*'''Test the most frequently occurring case first'''
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*'''Optimize the way you access global constants'''
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*'''Use explicit returns'''
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
*http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html
*http://www.infoq.com/news/2009/09/code-quality-metric-fu
*http://itsignals.cascadia.com.au/?p=7
*http://guides.rubyonrails.org/api_documentation_guidelines.html
*http://www.caliban.org/ruby/rubyguide.shtml
*http://en.wikipedia.org/wiki/Ruby_(programming_language)
*http://graidengarrison.weebly.com/1/post/2013/03/the-importance-of-coding-standards-in-net-development.html
*http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-17T21:51:09Z

Hsure: /* Performance Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby.<ref>http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages</ref> They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*'''Destructive operations are faster'''
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*'''For loops are faster than .each'''
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*'''Avoid calls to parse_date and strftime'''
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*'''Don’t use unnecessary block parameters'''
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*'''Know your gems'''
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*'''Test the most frequently occurring case first'''
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*'''Optimize the way you access global constants'''
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*'''Use explicit returns'''
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
*http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html
*http://www.infoq.com/news/2009/09/code-quality-metric-fu
*http://itsignals.cascadia.com.au/?p=7
*http://guides.rubyonrails.org/api_documentation_guidelines.html
*http://www.caliban.org/ruby/rubyguide.shtml
*http://en.wikipedia.org/wiki/Ruby_(programming_language)
*http://graidengarrison.weebly.com/1/post/2013/03/the-importance-of-coding-standards-in-net-development.html
*http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-17T21:45:11Z

Hsure: /* References */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*'''Destructive operations are faster'''
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*'''For loops are faster than .each'''
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*'''Avoid calls to parse_date and strftime'''
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*'''Don’t use unnecessary block parameters'''
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*'''Know your gems'''
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*'''Test the most frequently occurring case first'''
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*'''Optimize the way you access global constants'''
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*'''Use explicit returns'''
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
*http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html
*http://www.infoq.com/news/2009/09/code-quality-metric-fu
*http://itsignals.cascadia.com.au/?p=7
*http://guides.rubyonrails.org/api_documentation_guidelines.html
*http://www.caliban.org/ruby/rubyguide.shtml
*http://en.wikipedia.org/wiki/Ruby_(programming_language)
*http://graidengarrison.weebly.com/1/post/2013/03/the-importance-of-coding-standards-in-net-development.html
*http://stackoverflow.com/questions/6406112/why-are-ruby-method-calls-particularly-slow-in-comparison-to-other-languages

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-17T21:44:39Z

Hsure: /* Performance Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are expensive operations in ruby. They should be avoided to keep up the performance of the application.

*'''Use interpolated strings instead of concatenated strings'''
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*'''Destructive operations are faster'''
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*'''For loops are faster than .each'''
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*'''Avoid calls to parse_date and strftime'''
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*'''Don’t use unnecessary block parameters'''
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*'''Know your gems'''
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*'''Test the most frequently occurring case first'''
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*'''Optimize the way you access global constants'''
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*'''Use explicit returns'''
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
*http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html
*http://www.infoq.com/news/2009/09/code-quality-metric-fu
*http://itsignals.cascadia.com.au/?p=7
*http://guides.rubyonrails.org/api_documentation_guidelines.html
*http://www.caliban.org/ruby/rubyguide.shtml
*http://en.wikipedia.org/wiki/Ruby_(programming_language)
*http://graidengarrison.weebly.com/1/post/2013/03/the-importance-of-coding-standards-in-net-development.html

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-17T21:38:22Z

Hsure: /* Performance Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting affects the performance of the code proportionally with the increasing levels in loops. Limiting nesting to three levels is one good practice to keep the code's performance well.

*'''Avoid unnecessary variable assignments'''
: New programmers, often use unwanted variables in code. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.

*'''Reduce usage of disk I/O'''
: Disk I/O is a very costly operation as far as computing is concerned. Keeping it to the minimal improves the application response time drastically. Using disk I/O, makes the application extremely slow. Using storage systems such as memcached reduces disk I/O operations to a great extent as lot of data is kept in memory. The speed improvement while using a memory caching system is tremendous.

*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, to get benefited by this performance one needs to follow their guidelines.

*'''Avoid method calls as much as possible'''
: Method calls are very expensive operations and should be avoided when necessary.

*'''Use interpolated strings instead of concatenated strings'''
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*'''Destructive operations are faster'''
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*'''For loops are faster than .each'''
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*'''Avoid calls to parse_date and strftime'''
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*'''Don’t use unnecessary block parameters'''
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*'''Know your gems'''
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*'''Test the most frequently occurring case first'''
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*'''Optimize the way you access global constants'''
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*'''Use explicit returns'''
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
*http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html
*http://www.infoq.com/news/2009/09/code-quality-metric-fu
*http://itsignals.cascadia.com.au/?p=7
*http://guides.rubyonrails.org/api_documentation_guidelines.html
*http://www.caliban.org/ruby/rubyguide.shtml
*http://en.wikipedia.org/wiki/Ruby_(programming_language)
*http://graidengarrison.weebly.com/1/post/2013/03/the-importance-of-coding-standards-in-net-development.html

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-17T21:21:50Z

Hsure: /* Performance Guidelines */

== '''Ruby Coding Guidelines''' ==

Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Should use lowercase letter followed by other characters. Naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. average, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should succeed @, e.g. @color
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. The name should possibly be a verb e.g. move, display_details
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@color
*'''Constant'''
:Constant names usually start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names are recommended to be be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules), however, should probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. Class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

Ruby blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies. These strategies can be used to design classes accordingly as suitable for different types of applications.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
The key parameter on which a software application is rated is by its performance. It is the time taken by the application to respond to a user's request. Performance of ruby can be improved significantly by following certain coding guidelines, as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting not only slows your code down but also can make maintenance of the codebase difficult if it goes too many levels deep. Limiting nesting of loops and functions to three levels or less is a good rule of thumb to keep your code performant.
*'''Avoid unnecessary variable assignments'''
: New programmers, tend to assign variables more than necessary. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.
*'''Reduce usage of disk I/O'''
: Disk I/O is one of the biggest bottlenecks remaining in computing. Read/write operations to disk are extremely slow and it’s best to avoid using the disk whenever possible. Many people are now using software such as memcached which allows data to be stored in memory and only periodically written to disk. The speed improvement while using a memory caching system is tremendous.
*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, in order to take advantage of these performance gains you must be sure to program according to their guidelines.
*'''Avoid method calls as much as possible'''
: Method calls are very expensive operations and should be avoided when necessary.
*'''Use interpolated strings instead of concatenated strings'''
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*'''Destructive operations are faster'''
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*'''For loops are faster than .each'''
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*'''Avoid calls to parse_date and strftime'''
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*'''Don’t use unnecessary block parameters'''
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*'''Know your gems'''
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*'''Test the most frequently occurring case first'''
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*'''Optimize the way you access global constants'''
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*'''Use explicit returns'''
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----

Documentation comments can be created in accordance with [http://rdoc.sourceforge.net/ RDoc] and [http://yardoc.org/ YARD] syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything meaningfully.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== '''Code Analysis Tools''' ==

Ruby itself goes a long way towards helping developers write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual things one would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to increase. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses Ruby code and warns about design issues from the list configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of code written: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyzer, this can be used for duplication identification (a $99 license is needed for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== '''Summary''' ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== '''See Also''' ==
*http://www.caliban.org/ruby/rubyguide.shtml

== '''References''' ==
*http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html
*http://www.infoq.com/news/2009/09/code-quality-metric-fu
*http://itsignals.cascadia.com.au/?p=7
*http://guides.rubyonrails.org/api_documentation_guidelines.html
*http://www.caliban.org/ruby/rubyguide.shtml
*http://en.wikipedia.org/wiki/Ruby_(programming_language)
*http://graidengarrison.weebly.com/1/post/2013/03/the-importance-of-coding-standards-in-net-development.html

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-17T02:27:57Z

Hsure:

== '''Ruby Coding Guidelines''' ==

Designed and developed in the mid-1990s by Yukihiro "Matz" Matsumoto in Japan, Ruby embodies syntax inspired by Perl with Smalltalk-like features and was also influenced by Eiffel and Lisp. Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== '''Types of Guidelines''' ==
Coding guidelines in Ruby can be defined for individually for major sections that code consists of. Naming , Class Design , Member Design , Maintainability, Performance, Documentation and Layout guidelines are illustrated below. These guidelines contain sections common to all of these as well as sections which apply to each one individually.

=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*'''Local Variables'''
:Lowercase letter followed by other characters, naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. mileage, variable_xyz
*'''Instance Variables'''
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should be used after the @, e.g. @colour
*'''Instance Methods'''
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. If possible, the name should be a verb e.g. paint, close_the_door
*'''Class Variables'''
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@colour
*'''Constant'''
:Constant names start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*'''Class and Module'''
:Class names should be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules) should, however, probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*'''Global Variables'''
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*'''Model Naming Convention'''
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*'''Controller Naming Convention'''
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*'''View Naming Convention'''
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*'''Tests Naming Convention'''
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----
To implement object-oriented programming by using Ruby, one needs to first learn how to create objects and classes in Ruby.

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. The class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

One of the interesting things about Ruby is the way it blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
----
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance.
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* '''Profile your code regularly'''
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
Computer software performance, particularly software application response time, is an aspect of software quality that is important in human–computer interactions. Performance of Ruby based applications can be regulated by following certain coding guidelines, such as below.

*'''Avoid nesting loops more than three levels deep'''
: Nesting not only slows your code down but also can make maintenance of the codebase difficult if it goes too many levels deep. Limiting nesting of loops and functions to three levels or less is a good rule of thumb to keep your code performant.
*'''Avoid unnecessary variable assignments'''
: New programmers, tend to assign variables more than necessary. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.
*'''Reduce usage of disk I/O'''
: Disk I/O is one of the biggest bottlenecks remaining in computing. Read/write operations to disk are extremely slow and it’s best to avoid using the disk whenever possible. Many people are now using software such as memcached which allows data to be stored in memory and only periodically written to disk. The speed improvement while using a memory caching system is tremendous.
*'''Use Ruby Enterprise Edition'''
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, in order to take advantage of these performance gains you must be sure to program according to their guidelines.
*'''Avoid method calls as much as possible'''
: Method calls are very expensive operations and should be avoided when necessary.
*'''Use interpolated strings instead of concatenated strings'''
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*'''Destructive operations are faster'''
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*'''Avoid unnecessary calls to uniq on arrays'''
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*'''For loops are faster than .each'''
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*'''Use x.blank? over x.nil? || x.empty?'''
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*'''Avoid calls to parse_date and strftime'''
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*'''Don’t use unnecessary block parameters'''
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*'''Know your gems'''
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*'''Improve your algorithms before you try to improve your code'''
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*'''Test the most frequently occurring case first'''
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*'''Optimize the way you access global constants'''
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*'''Use explicit returns'''
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----
In languages files, RubyMine creates stubs of documentation comments on typing the opening tag and pressing Enter.

Documentation comments can be created in accordance with RDoc and YARD syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

When you create additional tags, RubyMine provides code completion that suggests the possible tag names.

The most common Documentation guidelines are listed below.
*Write simple, declarative sentences. Brevity is a plus: get to the point.
*Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...".
*Start comments in upper case. Follow regular punctuation rules:
<pre>
# Declares an attribute reader backed by an internally-named
# instance variable.
def attr_internal_reader(*attrs)
...
end
</pre>
*Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Documentation has to be concise but comprehensive. Explore and document edge cases.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*'''Spreading Code Out and Lining it Up'''
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything in a meaningful way.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalizing and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== Code Analysis Tools ==

Ruby itself goes a long way towards helping one write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>

The debugger can do all the usual sorts of things you would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to rise. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses your Ruby code and warns you about design issues from the list you configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of your code: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyser, this can be used for duplication identification (you need a $99 license for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

[[File:Code Analysis Outputs.png|frame|none|alt=Code Analysis Tool Results|Code Analysis Tool Results]]

== Summary ==
Ruby developers should follow a certain criteria or guidelines during software development. Coding standards are set of rules, guidelines and regulations on the manner of writing a code that helps programmers and developers read and understand quickly the source code that conforms to style and help avoid introducing misunderstanding and faults.

Particularly in Ruby development, coding standards are extremely important; therefore Ruby developers should put an importance to them. This is because these standards offer higher uniformity and consistency when writing code by different programmers. This could result in a code that's simple to know and preserve, thus reducing the project’s overall expenses.

Some of the benefits of using coding standards are:

*Easy to understand and maintained
*Boost the code’s readability
*Maintainable applications
*Eradicates complexity
*Separate documents look more appropriate

== See Also ==
*http://www.caliban.org/ruby/rubyguide.shtml

== References ==
*http://www.jetbrains.com/ruby/webhelp/documenting-source-code-in-rubymine.html
*http://www.infoq.com/news/2009/09/code-quality-metric-fu
*http://itsignals.cascadia.com.au/?p=7
*http://guides.rubyonrails.org/api_documentation_guidelines.html
*http://www.caliban.org/ruby/rubyguide.shtml
*http://en.wikipedia.org/wiki/Ruby_(programming_language)
*http://graidengarrison.weebly.com/1/post/2013/03/the-importance-of-coding-standards-in-net-development.html

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-16T23:27:18Z

Hsure: /* Importance of guidelines */

'''Ruby Coding Guidelines'''

Designed and developed in the mid-1990s by Yukihiro "Matz" Matsumoto in Japan, Ruby embodies syntax inspired by Perl with Smalltalk-like features and was also influenced by Eiffel and Lisp. Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== Types of Guidelines ==
=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*Local Variables
:Lowercase letter followed by other characters, naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. mileage, variable_xyz
*Instance Variables
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should be used after the @, e.g. @colour
*Instance Methods
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. If possible, the name should be a verb e.g. paint, close_the_door
*Class Variables
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@colour
*Constant
:Constant names start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*Class and Module
:Class names should be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules) should, however, probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*Global Variables
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*Model Naming Convention
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*Controller Naming Convention
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*View Naming Convention
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*Tests Naming Convention
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----
To implement object-oriented programming by using Ruby, one needs to first learn how to create objects and classes in Ruby.

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. The class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

One of the interesting things about Ruby is the way it blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance. <ref>Robert L. Glass: Facts and Fallacies of Software Engineering; Addison Wesley, 2003. </ref>
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* Profile your code regularly
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
Computer software performance, particularly software application response time, is an aspect of software quality that is important in human–computer interactions. Performance of Ruby based applications can be regulated by following certain coding guidelines, such as below.

*Avoid nesting loops more than three levels deep
: Nesting not only slows your code down but also can make maintenance of the codebase difficult if it goes too many levels deep. Limiting nesting of loops and functions to three levels or less is a good rule of thumb to keep your code performant.
*Avoid unnecessary variable assignments
: New programmers, tend to assign variables more than necessary. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.
*Reduce usage of disk I/O
: Disk I/O is one of the biggest bottlenecks remaining in computing. Read/write operations to disk are extremely slow and it’s best to avoid using the disk whenever possible. Many people are now using software such as memcached which allows data to be stored in memory and only periodically written to disk. The speed improvement while using a memory caching system is tremendous.
*Use Ruby Enterprise Edition
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, in order to take advantage of these performance gains you must be sure to program according to their guidelines.
*Avoid method calls as much as possible
: Method calls are very expensive operations and should be avoided when necessary.
*Use interpolated strings instead of concatenated strings
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*Destructive operations are faster
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*Avoid unnecessary calls to uniq on arrays
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*For loops are faster than .each
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*Use x.blank? over x.nil? || x.empty?
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*Avoid calls to parse_date and strftime
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*Don’t use unnecessary block parameters
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*Know your gems
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*Improve your algorithms before you try to improve your code
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*Test the most frequently occurring case first
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*Optimize the way you access global constants
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*Use explicit returns
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----
In languages files, RubyMine creates stubs of documentation comments on typing the opening tag and pressing Enter.

Documentation comments can be created in accordance with RDoc and YARD syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

When you create additional tags, RubyMine provides code completion that suggests the possible tag names.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*Spreading Code Out and Lining it Up
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything in a meaningful way.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalising and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== Code Analysis Tools ==
Ruby itself goes a long way towards helping one write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>
The debugger can do all the usual sorts of things you would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to rise. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses your Ruby code and warns you about design issues from the list you configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of your code: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyser, this can be used for duplication identification (you need a $99 license for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

== Summary ==
== See Also ==
== References ==

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-16T23:26:56Z

Hsure: /* Ruby Coding Guidelines */

'''Ruby Coding Guidelines'''

Designed and developed in the mid-1990s by Yukihiro "Matz" Matsumoto in Japan, Ruby embodies syntax inspired by Perl with Smalltalk-like features and was also influenced by Eiffel and Lisp. Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== Importance of guidelines ==

== Types of Guidelines ==
=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*Local Variables
:Lowercase letter followed by other characters, naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. mileage, variable_xyz
*Instance Variables
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should be used after the @, e.g. @colour
*Instance Methods
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. If possible, the name should be a verb e.g. paint, close_the_door
*Class Variables
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@colour
*Constant
:Constant names start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*Class and Module
:Class names should be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules) should, however, probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*Global Variables
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*Model Naming Convention
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*Controller Naming Convention
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*View Naming Convention
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*Tests Naming Convention
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----
To implement object-oriented programming by using Ruby, one needs to first learn how to create objects and classes in Ruby.

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. The class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

One of the interesting things about Ruby is the way it blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance. <ref>Robert L. Glass: Facts and Fallacies of Software Engineering; Addison Wesley, 2003. </ref>
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* Profile your code regularly
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
Computer software performance, particularly software application response time, is an aspect of software quality that is important in human–computer interactions. Performance of Ruby based applications can be regulated by following certain coding guidelines, such as below.

*Avoid nesting loops more than three levels deep
: Nesting not only slows your code down but also can make maintenance of the codebase difficult if it goes too many levels deep. Limiting nesting of loops and functions to three levels or less is a good rule of thumb to keep your code performant.
*Avoid unnecessary variable assignments
: New programmers, tend to assign variables more than necessary. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.
*Reduce usage of disk I/O
: Disk I/O is one of the biggest bottlenecks remaining in computing. Read/write operations to disk are extremely slow and it’s best to avoid using the disk whenever possible. Many people are now using software such as memcached which allows data to be stored in memory and only periodically written to disk. The speed improvement while using a memory caching system is tremendous.
*Use Ruby Enterprise Edition
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, in order to take advantage of these performance gains you must be sure to program according to their guidelines.
*Avoid method calls as much as possible
: Method calls are very expensive operations and should be avoided when necessary.
*Use interpolated strings instead of concatenated strings
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*Destructive operations are faster
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*Avoid unnecessary calls to uniq on arrays
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*For loops are faster than .each
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*Use x.blank? over x.nil? || x.empty?
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*Avoid calls to parse_date and strftime
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*Don’t use unnecessary block parameters
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*Know your gems
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*Improve your algorithms before you try to improve your code
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*Test the most frequently occurring case first
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*Optimize the way you access global constants
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*Use explicit returns
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----
In languages files, RubyMine creates stubs of documentation comments on typing the opening tag and pressing Enter.

Documentation comments can be created in accordance with RDoc and YARD syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

When you create additional tags, RubyMine provides code completion that suggests the possible tag names.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*Spreading Code Out and Lining it Up
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything in a meaningful way.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalising and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== Code Analysis Tools ==
Ruby itself goes a long way towards helping one write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>
The debugger can do all the usual sorts of things you would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to rise. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses your Ruby code and warns you about design issues from the list you configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of your code: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyser, this can be used for duplication identification (you need a $99 license for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

== Summary ==
== See Also ==
== References ==

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-16T23:26:23Z

Hsure: /* Code Analysis Tools */

= Ruby Coding Guidelines =

Designed and developed in the mid-1990s by Yukihiro "Matz" Matsumoto in Japan, Ruby embodies syntax inspired by Perl with Smalltalk-like features and was also influenced by Eiffel and Lisp. Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

Software programmers are highly recommended to follow these guidelines to help improve the readability of their source code and make software maintenance easier. Naming conventions, class and member design principles, maintainability, performance, documentation and layout are the important areas where these guidelines have to be followed. More important than the reasons for having a guideline is actually adhering to it consistently. Having a coding guideline documented and available means nothing if developers are not using it consistently.

__TOC__

== Importance of guidelines ==
== Types of Guidelines ==
=== Naming Guidelines ===
----
Ruby uses the first character of the name to help it determine it’s intended use.
The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

*Local Variables
:Lowercase letter followed by other characters, naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. mileage, variable_xyz
*Instance Variables
:Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should be used after the @, e.g. @colour
*Instance Methods
:Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. If possible, the name should be a verb e.g. paint, close_the_door
*Class Variables
:Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@colour
*Constant
:Constant names start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
*Class and Module
:Class names should be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules) should, however, probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
*Global Variables
:Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.
*Model Naming Convention
<pre>
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
</pre>

*Controller Naming Convention
<pre>
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
</pre>
*View Naming Convention
<pre>
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
</pre>
*Tests Naming Convention
<pre>
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml
</pre>

=== Class Design Guidelines ===
----
To implement object-oriented programming by using Ruby, one needs to first learn how to create objects and classes in Ruby.

A class in Ruby always starts with the keyword class followed by the name of the class. The name should always be in initial capitals. The class Customer can be displayed as:

<pre>
class Customer
end
</pre>

A class is terminated by using the keyword end. All the data members in the class are between the class definition and the end keyword.

One of the interesting things about Ruby is the way it blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies.

*'''The Visitor pattern''' is a way of traversing a collection without having to know the internal organization of that collection.
*'''Delegation''' is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
*The '''Singleton pattern''' is a way of ensuring that only one instantiation of a particular class exists at a time.
*The '''Observer pattern''' implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

Normally, all four of these strategies require explicit code each time they're implemented. With Ruby, they can be abstracted into a library and reused freely and transparently.

=== Member Design Guidelines ===
----
While defining class members, it is very important to keep in mind the access restrictions. Scope and life-time of class members are different for different restrictions, as illustrated below.

<pre>
public
totally accessible.
protected
accessible only by instances of class and direct descendants. Even through hasA relationships. (see below)
private
accessible only by instances of class (must be called nekkid no “self.” or anything else).
class A
# Restriction used w/o arguments set the default access control.
protected

def protected_method
# nothing
end
end

class B < A
def test_protected
myA = A.new
myA.protected_method
end

# Used with arguments, sets the access of the named methods and constants.
public :test_protected
end

b = B.new.test_protected
</pre>

=== Maintainability Guidelines ===
Maintainability guidelines are important to programmers for a number of reasons:
<blockquote>
*40%-80% of the lifetime cost of a piece of software goes to maintenance. <ref>Robert L. Glass: Facts and Fallacies of Software Engineering; Addison Wesley, 2003. </ref>
*Hardly any software is maintained for its whole life by the original author.
*Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
*If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.
</blockquote>
The following guidelines are to be followed to improve the software maintainability
* Profile your code regularly
: If you profile your code regularly you’ll be able to tell if the latest change to the code will have an adverse effect on performance. Integrate profiling into your testing process and make it automated to ensure that it’s not forgotten. Like unit testing and BDD([http://en.wikipedia.org/wiki/Behavior-driven_development Behavior-driven development]) profiling goes a long way.

=== Performance Guidelines ===
----
Computer software performance, particularly software application response time, is an aspect of software quality that is important in human–computer interactions. Performance of Ruby based applications can be regulated by following certain coding guidelines, such as below.

*Avoid nesting loops more than three levels deep
: Nesting not only slows your code down but also can make maintenance of the codebase difficult if it goes too many levels deep. Limiting nesting of loops and functions to three levels or less is a good rule of thumb to keep your code performant.
*Avoid unnecessary variable assignments
: New programmers, tend to assign variables more than necessary. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.
*Reduce usage of disk I/O
: Disk I/O is one of the biggest bottlenecks remaining in computing. Read/write operations to disk are extremely slow and it’s best to avoid using the disk whenever possible. Many people are now using software such as memcached which allows data to be stored in memory and only periodically written to disk. The speed improvement while using a memory caching system is tremendous.
*Use Ruby Enterprise Edition
: Ruby Enterprise edition provides up to [http://www.rubyenterpriseedition.com/faq.html#thirty_three_percent_mem_reduction 33% lower memory] usage. Though, in order to take advantage of these performance gains you must be sure to program according to their guidelines.
*Avoid method calls as much as possible
: Method calls are very expensive operations and should be avoided when necessary.
*Use interpolated strings instead of concatenated strings
: Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.
put “Hello there, #{name}!”
vs.
puts “Hello there, ” << name = “!”
*Destructive operations are faster
: Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
*Avoid unnecessary calls to uniq on arrays
: In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
*For loops are faster than .each
: When you use .each you encounter per-request execution; for loops avoid this expensive operation.
*Use x.blank? over x.nil? || x.empty?
: When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
*Avoid calls to parse_date and strftime
: Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
*Don’t use unnecessary block parameters
: If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
*Know your gems
: Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
*Improve your algorithms before you try to improve your code
: Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
*Test the most frequently occurring case first
: When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
*Optimize the way you access global constants
: Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
*Use explicit returns
: Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

=== Documentation Guidelines ===
----
In languages files, RubyMine creates stubs of documentation comments on typing the opening tag and pressing Enter.

Documentation comments can be created in accordance with RDoc and YARD syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

When you create additional tags, RubyMine provides code completion that suggests the possible tag names.

=== Layout Guidelines ===
----
Designing the layout of any application determines the readability factor for other developers.
Most followed order of code is as follows:

header block with author's name, Perforce Id tag and a brief description of what the program or library is for. 
require statements 
include statements 
class and module definitions 
main program section 

*Spreading Code Out and Lining it Up
:This is very important for readability. Basically the principle is to:
:*separate each component part by white space.
:*align everything in a meaningful way.
:As such one can easily scan up and down the code and see the patterns. This is very important not only for understanding the code, but also for looking for anomalies and as a tool for rationalising and consolidating the code.
:Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

== Code Analysis Tools ==
Ruby itself goes a long way towards helping one write clear code.

*'''The Ruby debugger''' is a library loaded into Ruby at run-time.
This is done as follows:
<pre>
ruby -r debug [
options
] [
programfile
] [
arguments
]
</pre>
The debugger can do all the usual sorts of things you would expect it to, such as set breakpoints, step into and over code, print out the call stack, etc.

While tools for the mainstream languages such as Java and C++ have reached a certain maturity, tools for Ruby are still growing. And they might be needed more and more as Ruby's usage spreads from early adopters to the early majority, and SLOC (Source Lines Of Code) continues to rise. Automatic tools can be used to detect several types of problems including inconsistent style, long methods and repeated code.

*[https://github.com/roodi/roodi/tree/master '''Roodi'''] (Ruby Object Oriented Design Inferometer) - this parses your Ruby code and warns you about design issues from the list you configured, ie: Class line count check, for loop check, parameter number check, cyclomatic checks and 10 other checks
*[https://github.com/troessner/reek '''Reek'''] - similar in concept to Roodi
*[https://github.com/devver/saikuro '''Saikuro'''] - designed to check cyclomatic complexity
*[https://github.com/seattlerb/flog '''Flog'''] - created by Ryan Davis, this computes a score of your code: the higher the score is, the worse your code is. ABC metrics (Assignments, Branches and Calls) are taken into account to compute the score
*[http://www.harukizaemon.com/simian/ '''Simian'''] - a similarity analyser, this can be used for duplication identification (you need a $99 license for commercial use)
*[https://github.com/seattlerb/flay '''Flay'''] - this is another free tool from Ryan Davis that finds structural similarities in code

== Summary ==
== See Also ==
== References ==

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-16T23:26:05Z

Hsure: /* Code Analysis Tools */

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-16T23:25:21Z

Hsure: /* Code Analysis Tools */

File:DSC01182.JPG

2013-09-16T23:23:10Z

Hsure: uploaded a new version of "File:DSC01182.JPG"

File:DSC01182.JPG

2013-09-16T23:15:15Z

Hsure:

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-16T23:12:52Z

Hsure: /* Code Analysis Tools */