Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T20:27:46Z

Pyadla: /* Appendix: setup issues */

=== E811. 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 2013/oss E811 syn

2013-10-30T20:16:10Z

Pyadla: /* E811. Refactor & test submitted_content_controller & submitted_content_helper */

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T20:15:55Z

Pyadla:

=== E811. 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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T20:13:52Z

Pyadla: /* Future Work */

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T20:11:13Z

Pyadla: /* Appendix: setup issues */

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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>
Code clean up done besides the requirements of the project.
Design choice for the changes made in partial files such that code reuse can be maximised.
Cucumber testing scenarios for the changes made: Work In Progress
Further code smells need to be processed for more elegance.

==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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T20:10:29Z

Pyadla: /* Future Work */

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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>
Code clean up done besides the requirements of the project.
Design choice for the changes made in partial files such that code reuse can be maximised.
Cucumber testing scenarios for the changes made: Work In Progress
Further code smells need to be processed for more elegance.

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:42:54Z

Pyadla: /* List of Code Smells identified and removed */

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:42:31Z

Pyadla: /* Appendix: setup issues */

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:41:48Z

Pyadla: /* Appendix: setup issues */

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:38:41Z

Pyadla: /* Appendix: setup issues */

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:37:57Z

Pyadla: /* Appendix: setup issues */

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:36:16Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

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
 
In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:33:09Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===
 
== '''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==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. 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

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:23:11Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

== '''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==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T19:05:21Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

== '''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.
*Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
*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.
*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.

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:53:36Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

== '''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>

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:51:05Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

== '''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>

*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]]

*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.

*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>

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:47:04Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

== '''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>

*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]]

*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.

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:37:45Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

== '''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>

*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]]

*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]]

5. 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:

Modified code reduces the method length and increases Readability.

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:35:25Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

== '''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>

*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]]

*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]]

5. 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:

Modified code reduces the method length and increases Readability.

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

File:Filepath.png

2013-10-30T18:34:43Z

Pyadla:

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:33:41Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

== '''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>

*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]]

*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.png|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.png|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]]

5. 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:

Modified code reduces the method length and increases Readability.

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

File:Fpath.png

2013-10-30T18:32:41Z

Pyadla:

File:Unzip file mod.JPG

2013-10-30T18:26:13Z

Pyadla:

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:21:21Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

==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>

*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]]

3. 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:

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:

4. Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

5. 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:

Modified code reduces the method length and increases Readability.

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:20:11Z

Pyadla:

=== E811. Refactor & test submitted_content_controller & submitted_content_helper ===

==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>

*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.

3. 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:

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:

4. Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

5. 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:

Modified code reduces the method length and increases Readability.

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T18:12:42Z

Pyadla:

== E811. Refactor & test submitted_content_controller & submitted_content_helper ==

==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>

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2.

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

3. 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:

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:

4. Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

5. 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:

Modified code reduces the method length and increases Readability.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

File:Display change.png

2013-10-30T17:30:56Z

Pyadla:

File:Display variable.png

2013-10-30T17:30:40Z

Pyadla:

File:Unzip file.JPG

2013-10-30T17:24:50Z

Pyadla:

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T17:23:32Z

Pyadla:

== E811. Refactor & test submitted_content_controller & submitted_content_helper ==

==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>

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2. 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.

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

3. 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:

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:

4. Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

5. 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:

Modified code reduces the method length and increases Readability.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T17:20:24Z

Pyadla:

== E811. Refactor & test submitted_content_controller & submitted_content_helper ==

==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:

[[File:New method.jpg|frame|none|alt=Refactored method|Refactored method]]

==Future Work==

==Appendix: setup issues==

Git repository: https://github.com/hsure/expertiza
Application URL: 152.1.13.219::3000

Steps to setup the project:
1. 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
2. Confirm the sdk for RubyMine to ruby1.9.3 using File -> Settings
3. Run bundle install
4. Run - rake db:create:all
5. Run - rake db:migrate
6. From the Expertiza folder (project root) execute the command “rails server”

You should be able to view the test Database in MySQL in the following way:

Use the following credentials to explore the application:
Username: admin (Administrator)
Password: admin

Username: sample (User)
Password: sample

In order to test, login with user credentials and navigate to Assignments page. In Homework1 select ‘Your work’ and submit a hyperlink.

Code Changes:
1.

2. 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.

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

3. 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:

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:

4. Below is another name change from ‘fpath’ to ‘file_path’ which is made to eliminate the most common code smell ‘Excessively short identifiers’.

5. 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:

Modified code reduces the method length and increases Readability.

List of Code Smells identified and removed:
• Duplicated code: Identical or very similar code exists in more than one location.
• Long method: A method, function, or procedure that has grown too large.
• Too many parameters: A long list of parameters in a procedure or function make readability and code quality worse.
• 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.
• 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.

File:New method.JPG

2013-10-30T17:16:59Z

Pyadla:

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T03:46:55Z

Pyadla: /* E811. Refactor & test submitted_content_controller & submitted_content_helper */

== E811. Refactor & test submitted_content_controller & submitted_content_helper ==

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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T03:46:24Z

Pyadla: /* E811. Refactor & test submitted_content_controller & submitted_content_helper */

== E811. Refactor & test submitted_content_controller & submitted_content_helper ==

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.

CSC/ECE 517 Fall 2013/oss E811 syn

2013-10-30T03:45:37Z

Pyadla: Created page with " == E811. Refactor & test submitted_content_controller & submitted_content_helper =="

== E811. Refactor & test submitted_content_controller & submitted_content_helper ==

CSC/ECE 517 Fall 2013

2013-10-30T03:44:13Z

Pyadla:

* [[ CSC/ECE 517 Fall 2012/ch1 1w23 ph ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w30 nn]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w21 w]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w01 aj]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w24 nv]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w29 rkld]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w25 aras]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w30 ps]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w19 rj]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w18 bs]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w17 pk]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w22 ss]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w12 vn]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w14 st]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w08 cc]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w10 ga ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w26 as ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w27 ma ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w13 aa ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w11 sv ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w07 d ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w20 gq ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w03 ss ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w28 nm ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w02 pp ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w6 zs ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w04 y ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w05 st ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w09 hs ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w32 av ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w48 x ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w43 av]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w46 ka]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w33 aa]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w35 sa ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w39 as ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w31 vm ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w43 sm ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w44 s ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w47 ka ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w34 fs ]]
* [[ CSC/ECE 517 Fall 2013/ch1 1w40 ao ]]
* [[ CSC/ECE 517 Fall 2013/oss fmv ]]
* [[ CSC/ECE 517 Fall 2013/oss vna ]]
* [[ CSC/ECE 517 Fall 2013/oss paa ]]
* [[ CSC/ECE 517 Fall 2013/oss mapFeeds ]]
* [[ CSC/ECE 517 Fall 2013/oss ssp ]]
* [[ CSC/ECE 517 Fall 2013/ch2 0e808 nsv ]]
* [[ CSC/ECE 517 Fall 2013/oss aoa ]]
* [[ CSC/ECE 517 Fall 2013/oss cmh ]]
* [[ CSC/ECE 517 Fall 2013/oss ans ]]
* [[ CSC/ECE 517 Fall 2013/oss ssv]]
* [[ CSC/ECE 517 Fall 2013/oss E818 mra ]]
* [[ CSC/ECE 517 Fall 2013/oss SocialMediaFeeds ]]
* [[ CSC/ECE 517 Fall 2013/oss E811 syn ]]

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-24T20:12:21Z

Pyadla: /* See Also */

== '''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
*[https://www.ruby-toolbox.com/categories/code_metrics '''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
*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:11:36Z

Pyadla: /* 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
*[https://www.ruby-toolbox.com/categories/code_metrics '''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-24T20:09:35Z

Pyadla: Undo revision 78480 by Pyadla (talk)

== '''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://www.ruby-toolbox.com/categories/code_metrics '''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:23:35Z

Pyadla: /* 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.

*[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:22:30Z

Pyadla: /* 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.

*[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://www.ruby-toolbox.com/categories/code_metrics '''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-23T18:33:07Z

Pyadla: /* See Also */

== '''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.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
*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-23T18:24:22Z

Pyadla: /* See Also */

== '''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.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
*https://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*https://www.ruby-lang.org/en/documentation/
*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-23T18:19:51Z

Pyadla: /* See Also */

== '''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.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
*https://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*https://www.ruby-lang.org/en/documentation/
*https://www.ruby-lang.org/en/documentation/

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

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-23T18:17:57Z

Pyadla: /* See Also */

== '''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.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
*https://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/
*https://www.ruby-lang.org/en/documentation/

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

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-23T18:17:28Z

Pyadla: /* See Also */

== '''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.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
*https://github.com/styleguide/ruby
*http://www.ruby-doc.org/docs/ProgrammingRuby/

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

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-23T18:13:09Z

Pyadla: /* Performance Guidelineshttp://blog.monitis.com/index.php/2012/02/08/20-ruby-performance-tips/ */

== '''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.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
*https://github.com/styleguide/ruby

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

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-23T17:58:28Z

Pyadla: /* Class Design 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.
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:

<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.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
*https://github.com/styleguide/ruby

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

CSC/ECE 517 Fall 2012/ch1 1w23 ph

2013-09-23T17:50:58Z

Pyadla: /* Naming Guidelineshttp://itsignals.cascadia.com.au/?p=7 */

== '''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.

*'''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:

<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.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
*https://github.com/styleguide/ruby

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