CSC/ECE 517 Fall 2012/ch1 1w23 ph

From Expertiza_Wiki
Jump to navigation Jump to search

Ruby Coding Guidelines

Designed and developed in the mid-1990s by Yukihiro "Matz" Matsumoto in Japan, Ruby embodies syntax inspired by Perl with Smalltalk-like features and was also influenced by Eiffel and Lisp. Ruby Coding Guidelines include best practices followed generally for most of the object oriented programming languages as Ruby is entirely 'Object Oriented'. Also known as 'Ruby Coding conventions', these are a set of guidelines that recommend programming style, practices and methods for each aspect of a piece of program written in Ruby.

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

Types of Guidelines

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

Naming Guidelines

Ruby uses the first character of the name to help it determine it’s intended use. The standard Ruby file extension is .rb, although many people working on UNIX-like systems don't bother with it for stand-alone scripts. Whether or not one uses it for scripts is up to them, but they will need to use it for library files or they will not be found by the interpreter.

  • Local Variables
Lowercase letter followed by other characters, naming convention states that it is better to use underscores rather than camelBack for multiple word names, e.g. mileage, variable_xyz
  • Instance Variables
Instance variables are defined using the single "at" sign (@) followed by a name. It is suggested that a lowercase letter should be used after the @, e.g. @colour
  • Instance Methods
Method names should start with a lowercase letter, and may be followed by digits, underscores, and letters. If possible, the name should be a verb e.g. paint, close_the_door
  • Class Variables
Class variable names start with a double "at" sign (@@) and may be followed by digits, underscores, and letters, e.g. @@colour
  • Constant
Constant names start with an uppercase letter followed by other characters. Constant objects are by convention named using all uppercase letters and underscores between words, e.g. THIS_IS_A_CONSTANT
  • Class and Module
Class names should be nouns. In the case of modules, it's harder to make a clear recommendation. The names of mix-ins (which are just modules) should, however, probably be adjectives, such as the standard Enumerable and Comparable modules. Class and module names starts with an uppercase letter, by convention they are named using MixedCase, e.g. module Encryption, class MixedCase
  • Global Variables
Starts with a dollar ($) sign followed by other characters, e.g. $global

Considering customer order information as the data being used for an application, below naming guidelines give an idea of good class/table/file names.

  • Model Naming Convention
Table: orders
Class: Order
File: /app/models/order.rb
Primary Key: id
Foreign Key: customer_id
Link Tables: items_orders
  • Controller Naming Convention
Class: OrdersController
File: /app/controllers/orders_controller.rb
Layout: /app/layouts/orders.html.erb
  • View Naming Convention
Helper: /app/helpers/orders_helper.rb
Helper Module: OrdersHelper
Views: /app/views/orders/… (list.html.erb for example)
  • Tests Naming Convention
Unit: /test/unit/order_test.rb
Functional: /test/functional/orders_controller_test.rb
Fixtures: /test/fixtures/orders.yml

Class Design Guidelines

To implement object-oriented programming by using Ruby, one needs to first learn how to create objects and classes in Ruby.

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

class Customer
end

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

One of the interesting things about Ruby is the way it blurs the distinction between design and implementation. Ideas that have to be expressed at the design level in other languages can be implemented directly in Ruby. To help in this process, Ruby has support for some design-level strategies.

  • The Visitor pattern is a way of traversing a collection without having to know the internal organization of that collection.
  • Delegation is a way of composing classes more flexibly and dynamically than can be done using standard inheritance.
  • The Singleton pattern is a way of ensuring that only one instantiation of a particular class exists at a time.
  • The Observer pattern implements a protocol allowing one object to notify a set of interested objects when certain changes have occurred.

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

Member Design Guidelines

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

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

Maintainability Guidelines

Maintainability guidelines are important to programmers for a number of reasons:

  • 40%-80% of the lifetime cost of a piece of software goes to maintenance. <ref>Robert L. Glass: Facts and Fallacies of Software Engineering; Addison Wesley, 2003. </ref>
  • Hardly any software is maintained for its whole life by the original author.
  • Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
  • If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

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(Behavior-driven development) profiling goes a long way.

Performance Guidelines

Computer software performance, particularly software application response time, is an aspect of software quality that is important in human–computer interactions. Performance of Ruby based applications can be regulated by following certain coding guidelines, such as below.

  • Avoid nesting loops more than three levels deep
Nesting not only slows your code down but also can make maintenance of the codebase difficult if it goes too many levels deep. Limiting nesting of loops and functions to three levels or less is a good rule of thumb to keep your code performant.
  • Avoid unnecessary variable assignments
New programmers, tend to assign variables more than necessary. A great example is when someone defines a variable to store a return value and then returns that variable; just return the value directly.
  • Reduce usage of disk I/O
Disk I/O is one of the biggest bottlenecks remaining in computing. Read/write operations to disk are extremely slow and it’s best to avoid using the disk whenever possible. Many people are now using software such as memcached which allows data to be stored in memory and only periodically written to disk. The speed improvement while using a memory caching system is tremendous.
  • Use Ruby Enterprise Edition
Ruby Enterprise edition provides up to 33% lower memory usage. Though, in order to take advantage of these performance gains you must be sure to program according to their guidelines.
  • Avoid method calls as much as possible
Method calls are very expensive operations and should be avoided when necessary.
  • Use interpolated strings instead of concatenated strings
Interpolated strings are faster than concatenated strings in almost all interpreted languages; Ruby is no exception. Using the << operator makes a method call which and method calls should be avoided when possible.

put “Hello there, #{name}!” vs. puts “Hello there, ” << name = “!”

  • Destructive operations are faster
Ruby’s in-place methods that modify the actual value instead of working on a copy of it are much faster, but be careful as they sometimes behave strangely (i.e., for!)
  • Avoid unnecessary calls to uniq on arrays
In many cases methods are already calling uniq on an array and there’s no need for you to call it yet again.
  • For loops are faster than .each
When you use .each you encounter per-request execution; for loops avoid this expensive operation.
  • Use x.blank? over x.nil? || x.empty?
When using ActionPack there’s no need for x.nil? or x.empty?; x.blank? checks for both of these.
  • Avoid calls to parse_date and strftime
Both of these are very expensive operations. Use regular expressions when parsing out date/time components.
  • Don’t use unnecessary block parameters
If you won’t be using the parameter in the block don’t specify it in the parameter list. Go through your code and ensure that any parameters declared are used or removed.
  • Know your gems
Not all libraries are created with performance in mind. Many gems are slapped together to solve a particular problem that author was having. Before you introduce a new gem into your performance-oriented production codebase be sure to perform thorough benchmarking and testing against other gems that perform the same tasks.
  • Improve your algorithms before you try to improve your code
Algorithmic improvements are almost always going to have more of an impact on the performance of your code than tweaks to the way your code is written will. Make sure your algorithm is designed to be efficient and has no extraneous methods or calls. Also, test for most frequent cases first and exit loops as soon as possible.
  • Test the most frequently occurring case first
When using if statements or a case statement always test the cases in the order that they occur most frequently. This allows less code to run before a decision is made. It may not seem like much but over several hundred or thousand runs through the decision logic you’ll notice a definite performance gain.
  • Optimize the way you access global constants
Be sure to precede a global constant with it’s namespace and the double colon operator (Namespace::constant_name) to reduce the time needed to query the library.
  • Use explicit returns
Although Ruby will automatically return the result of the last completed operation if no return value is provided you should use explicit return values. Explicit returns are faster, especially in older Ruby versions such as 1.8.x.

Documentation Guidelines

In languages files, RubyMine creates stubs of documentation comments on typing the opening tag and pressing Enter.

Documentation comments can be created in accordance with RDoc and YARD syntax. Note that RDoc highlighting in documentation comments can be turned enabled or disabled in the Appearance page of the editor settings.

When you create additional tags, RubyMine provides code completion that suggests the possible tag names.

Layout Guidelines

Designing the layout of any application determines the readability factor for other developers. Most followed order of code is as follows:

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

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

Code Analysis Tools

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

  • The Ruby debugger is a library loaded into Ruby at run-time.

This is done as follows: 

ruby -r debug [
            options
            ] [
            programfile
            ] [
            arguments
            ]

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

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

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

Summary

See Also

References

Retrieved from "https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2012/ch1_1w23_ph&oldid=76373"