CSC/ECE 517 Fall 2012/ch1 1w23 ph

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

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 rationalising and consolidating the code.

Code that has a lot of 'noise' - a lot of unnecessary variation and untidiness - is code that one can waste a lot of time working on. Well written and formatted code is code that is easy and quick to work with. It is code that allows one to easily 'see the wood from the trees'.

Code Analysis Tools

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

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

This is done as follows:

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

File:How to add an image.ogv

Video tutorial showing how to add an image thumbnail to a Wikipedia page