Ruby Coding Standards

Wiki ▸ Ruby Coding Standards

Contents

1. Introduction
2. Ruby Coding Standards
   1. General Guidelines
   2. References
   3. Project Layout
   4. Naming
   5. Files
   6. Classes
   7. Functions
   8. General
   9. Formatting

1. Introduction

The OpenStudio Ruby API includes a mix of compiled extensions to the OpenStudio C++ API as well as pure Ruby libraries. These elements are packaged together and included in the OpenStudio installer. Centralizing all OpenStudio functionality to a single install location allows measures or other scripts to reference the OpenStudio API in a standard way across computers and projects. The OpenStudio Ruby coding standards generally follow the OpenStudio C++ coding standards. In this chapter we only describe points of departure or clarify places where the C++ coding standards conflict with normal Ruby conventions.

2. Ruby Coding Standards

This document describes the preferred coding standards for Ruby code written for OpenStudio. The core of OpenStudio is the C++ API. Functionality in the OpenStudio C++ API is exported to several languages (including Ruby) via SWIG. Therefore, the most critical pieces of OpenStudio are written in C++ so they can be shared across all languages. When generating bindings for a specific language, some effort is taken to adopt the OpenStudio C++ API to the specific standards and features of that language. However, this is not always possible and you will see C++ coding style in the generated extensions. The compiled portions of the OpenStudio Ruby API generated by SWIG attempt to follow the standards in this document where possible. Portions of OpenStudio written in pure Ruby follow the standards in this document more closely. Ruby code written for measures follows these guidelines along with other measure specific recommendations described in the OpenStudio Measure Writing Guide.

2.1. General Guidelines

These guidelines are not hard and fast rules, but rather general suggestions to keep in mind when making design decisions.

• Keep your code as DRY (Do not repeat yourself) as possible, factor out common pieces of code into reusable classes or functions
• Balance between Ruby magic and readable code
• Use the Rubocop static code analyzer to inspect your code

2.2. References

Most of these standards are based on the Ruby Style Guide

2.3. Project Layout

The following name conventions are in place for Ruby files:

To limit complexity of Ruby include paths, all Ruby tests and scripts are assumed to be part of the OpenStudio library, that the lib directory is in the user's Ruby path, and that all required shared libraries are in the system's path (this is achieved during the require 'openstudio' call). Therefore, all Ruby scripts and libraries should refer to each other relative to the lib directory.

2.3.1. Directory Structure

Ruby is full of conventions and these should be respected in order to enable other Ruby based tools when possible. The directory structure of a Ruby project should have the following conventions

1. bin - Any executables
2. test - Unit test directory
3. spec - RSpec test directory
4. lib - Library directory containing subdirectories of the modules and source files
5. ext - Native extensions

The name of the directories shall be the snake cased version of the Module or Class name

File names shall be snake cased, typically conforming to the snake cased version of the Module or Class name.

2.3.2. Source Files

The following are common files used in Ruby and the expected extensions (case sensitive)

1. Rakefile - Rakefile
2. Gemfile - Gemfile
3. Ruby Files - .rb
4. Embedded Ruby Files - .rb.erb
5. Test Files - *_test.rb
6. Spec Files - *_spec.rb

2.4. Naming

The top level module for OpenStudio code is OpenStudio. Sub modules are also used and follow the C++ namespaces for SWIG extensions. Other conventions are:

• Classes are upper camel case, e.g. DetailedGeometry
• OpenStudio Member functions and local variables are lower camel case, e.g. addVertex and timeOfDay
• Ruby based member functions and local variables are snake cased, e.g. add_vertex_ruby and time_of_day_ruby
• Do not start the name of the function with get_ unless the function takes one or more arguments
• Enumerations are snake cased and symbolized, e.g. enum items{:small_items, :big_items}
• Unit test cases are upper camel case and post-fixed with _test, individual tests are upper camel cased and prefixed by test_. The idea is that test cases be easily recognizable in standard output when running a large number of tests, use _ to indicate spaces for greater readability.

2.5. Mixins

Use Mixins with caution in order to maintain code readability.

2.6. Unit Tests

We assume that C++ portions of OpenStudio are sufficiently tested using the C++ unit tests. Therefore, we do not require that all tests be duplicated for Ruby. However, we do encourage some testing of the Ruby extensions, particularly in areas where SWIG does something novel to the exported classes (e.g. changes a name, maps types, etc). Pure Ruby libraries should be tested completely in Ruby. These tests are then ported to C++ unit tests when the functionality is added to the C++ code base.

2.7. Indentation and Wrapping

We standardize on the following formatting conventions to improve code readability:

1. Wrap lines at 100 columns. If a line needs to be split, then the split should occur at some functional location (e.g., before/after the operator) and not just after the 100^th character.
2. Tab character is two spaces

2.8. Comments

Documentation is an important part of any source code. Even the most well written code is hard to understand or maintain if it is not properly commented. Comments should be made in RDoc format for documentation generation. The developer is encouraged to insert as many comments as needed to explain the code, not just the minimum required.

2.8.1. Documentation

Document code in RDoc format.