Стандарт кодирования Ruby в Flatsoft/Flatsourcing

Стандарт кодирования Ruby.rdoc

Структура программы¶ ↑

• require выражения

• include выражения

• определение классов и модулей

• основная часть программы

• код для тестирования

Исключения¶ ↑

Когда вы используете исключения в своей программе или библиотеке разумно будет создать базовый класс для всех исключений. Это позволит в дальнейшем более удобно обрабатывать и выводить ошибки.

module MyModule
  class MyError < StandardError; end
  class CreateError < ResourceError; end
  class DestroyError < ResourceError; end
end

Для отлова исключений используйте блок rescue. Для завершения выполнения программы в случае появления исключения используйте блок ensure.

begin
  file = open("/tmp/some_file", "w")
  # do stuff here
ensure
  file.close
end

При использовании rescue внутри методов части begin end можно опустить. Такое написание является предпочтительным.

def my_method
  # получаем исключение
rescue => e # ловим исключение
  # обрабатываем исключение
end

Так же можно использовать rescue для получения значения в случае, если метод кидает исключение:

item = hash[:key][:there_is_no_such_key] rescue nil

Однако нужно стараться избегать такого способа, и использовать дополнительные методы для проверки:

hash = {:key => []}
item = h[:key].include?(:there_is_no_such_key) ? h[:key][:there_is_no_such_key] : 0

Глобальные переменные¶ ↑

Глобальные переменные можно использовать в скриптах, которые необходимо быстро создать и которые никогда не будет использованы вновь. Использование глобальных переменных может вызывать конфликты имен в больших программах. По этой причине использование глобальных переменных стараются избегать.

Исключения:

• программы однострочники: если вы запускаете Ruby как ruby -e, то в таких программах можно использовать глобальные переменные;

• предопределенные глобальные переменные такие как: $., $! and $?. Бывает необходимо их использовать. Для того чтобы улучшить читабельность кода можно использовать require 'English'

Булевые выражения¶ ↑

В Ruby nil и false воспринимается как ложь, а все остальные значения как истина.

Следует избегать написания сложных выражений с применением unless

unless quiz.result0_file_size.blank? ||
  quiz.result25_file_size.blank? ||
  quiz.result50_file_size.blank? ||
  quiz.result75_file_size.blank? # красиво, но сложно читается

if !quiz.result0_file_size.blank? &&
  !quiz.result25_file_size.blank? &&
  !quiz.result50_file_size.blank? &&
  !quiz.result75_file_size.blank? # лучше писать с использованием if

Передача параметров по умолчанию¶ ↑

При определении метода можно указать значения для параметров, если они не были заданы при вызове.

def foo(a, b = 0, c = "zip")
  ...
end

Создание класса ¶ ↑

В Ruby есть несколько способов создания нового объекта. К примеру, нижеперечисленные вызовы эквивалентны:

foo = ""
foo = String.new

foo = []
foo = Array.new

foo = {}
foo = Hash.new

Предпочтений как создавать классы такого типа нет, но важно понимать, что когда вы создаете класс используя конструктор “new”, то ему может быть передан один или несколько атрибутов или блок для вычисления.

Выполнение кода по мере прочтения¶ ↑

Ruby является динамическим языком, это означает, что код может быть создан и выполнен на лету. Т.е. вы можете определить новые классы и методы, а также перегрузить необходимые операторы. Cуществующие классы можно открыть и дополнить новыми методами, изменить работу старых методов.

Это дает возможность для гибкого и эффективного кодирования. Нужно быть осторожным при использование техники мета-программирования, потому что для этого требуются глубокие знания логики работы Ruby, не понимание основных принципов может привести к трудновыловимым ошибкам.

Старайтесь не использовать Kernel#eval, попробуйте решить задачу при помощи Object#send, Module#class_eval, Module#module_eval и Object#instance_eval там, где это возможно.

Точка с запятой¶ ↑

Ruby позволяет использовать “;” в качестве разделителя выражений. Это означает, что вы можете записать несколько выражений в одну строчку разделив их “;”.

($stderr.puts "Error!"; exit 1) unless x == 2

Но, вообще говоря, это выглядит очень некрасиво, поэтому старайтесь использовать такой стиль в крайних случаях.

Длина строки¶ ↑

Максимальная длина строчки кода в вашей программе не должна превышать 80 символов или даже 79. Исключением являются только регулярные и другие выражения, которые проблематично разделить на несколько строк.

Отступы¶ ↑

В Ruby сообществе принято использовать для отступов два пробела. Не используйте табуляцию, которая может содержать пробелы и быть изменяемой длины.

Пустые строки¶ ↑

Рекомендуется вставлять две пустые строки между определениями классов и модулей и одну пустую строку между методами. Пустые строки не должны содержать пробелов.

Пробелы¶ ↑

Используйте пробелы для отделения операторов, кроме операторов присвоения по умолчанию ||=

a = b # правильно
a=b   # неправильно

Используйте пробелы для улучшения читаемости сложных выражений, но не используйте пробел, чтобы отделить метод от его списка параметров.

foo.bar(baz)   # правильно
foo.bar( baz ) # допустимо
foo.bar (baz)  # недопустимо

Не ставьте пробел перед запятой, ставьте после.

Комментарии¶ ↑

Описывайте документацию к вашим библиотекам используя “RDoc”:rdoc.sourceforge.net/doc/index.html

Добавляйте пустую закомментированную строку между комментарием и методом, классом или модулем для большей читаемости.

# This method returns the answer to the universe.
#
def answer
  42
end

Строки¶ ↑

Для вывода строк, если не требуется интерполяция переменных в них, то лучше использовать одинарные кавычки, они работают быстрее.

foo = "bar"
x = 'foo = #{foo}'  => "foo = #{foo}"
x = "foo = #{foo}"  => "foo = bar"

Так же существуют альтернативы для кавычек

x = sprintf("foo = %s", foo)
x = "foo = %s" % [foo]
x = %Q(works like a "double-quoted" string and embedded " characters work fine)
x = %q(a 'single'-quoted string with embedded ' characters)
x = %w[an array of words]

Так же для многострочных строк можно использовать HEREDOC

print <<EOF
  Usage: foo <bar>

  Call foo with bar as an argument
EOF

Приоритет ¶ ↑

Различайте приоритет у операторов && и and, || и or.

puts nil || "foo"   # parses to: puts( nil || "foo" )  => prints "foo"
puts nil or "foo"   # parses to: puts( nil ) || "foo"  => prints nil

Старайтесь всегда использовать && и || вместо and и or.

Блоки¶ ↑

Если выражение в блоке помещается на одну строку то принято использовать { и }, если выражение занимает несколько строк, то нужно использовать do и end

[1, 2, 3].collect { |i| i*i } 
[1, 2, 3].each do |i|
  str = "i * i = #{i * i}"
  puts(str)
end

Определение области видимости¶ ↑

Всегда описывайте область видимости метода при помощи public, private, protected. Старайтесь не использовать Object#instance_variable_set и Object#instance_variable_get, если только вы не делаете действительно что-то умное.

Для описание методов класса предпочтительно использовать конструкцию:

class << self
  def method
  end
end

вместо

def self.method
end

Порядок описания методов класса:

class MyClass
  def public_instance_method
  end

  class << self
    def public_class_method
    end
  end

  private

  def private_instance_method
  end

  class << self
    private

    def private_class_method
    end
  end
end

Наименование¶ ↑

Избегайте однобуквенных названий везде, кроме каунтеров и итераторв. Обычно скрипты Ruby имеют расширение .rb, однако в мире UNIX считается нормальным не указывать расширение у скрипта.

Название классов и модулей должны следовать camel case:

Class BigFatObject

Название модуля должно нести понятный смысл.

Константы должны состоять из символов в верхнем регистре и подчеркиваний:

BigFatObject::MAX_SIZE

Названия методов должны состоять из символов в нижнем регистре и подчеркиваний:

BigFatObject#pare_down

Названия переменных должны состоять из символов в нижнем регистре и подчеркиваний:

@response_code

Скобки¶ ↑

Ruby позволяет во многих случаях не использовать скобки, однако лучше их использовать всегда за исключением:

• общепринятых методов, таких как Kernel#require, Module#include, Kernel#p and the attr_*

• если первый параметр метода сивол или строка

  some_method “a string” some_method :symbol some_method :symbol, :foo => ‘bar’ some_method(“a string”) || true some_method(an_object)