Следующие правила позволяют поддерживать код Rubinius в порядке. Если у вас возникают вопросы по стилю, задайте их на IRC канале #rubinius на сервере irc.freenode.net.
Не вставляйте пробел между условием и скобкой.
Используйте if(1)
, а НЕ if (1)
Открывающую фигурную скобку помещайте на одну строчку с условием или объявлением функции.
Всегда используйте фигурные скобки, даже если их можно опустить.
Используйте скобки для явной приоритизации (в пределах разумного).
Альтернативные варианты функций должны именоваться таким образом, чтобы было понятно, чем они отличаются от основной. Допустим, есть функция ‘person()’ и вы хотите сделать альтернативную функцию, которая принимает дополнительный параметр “имя”, в таком случае имя функции должно быть ‘person_with_name(char *name)’ или ‘person_with_details(char *name, …)’, а ни в коем случае не ‘person1(char *name)’.
Методы: Пытайтесь реализовывать ваши методы коротко–не более 1 экрана и пытайтесь придерживаться принципа DRY в разумных пределах. В целом, общая функциональность должна быть абстрагирована в методы-помощники (которые вы можете сделать приватными), но в некоторых случаях, особенно работая с Core, слепое следование DRY может мешать вам, например если вы вынуждены маневрировать среди различных ошибочных условий.
Имена методов должны быть ясными, выразительными и осмысленными. За некоторым исключением, старайтесь не использовать знаки подчеркивания для “защиты” методов (‘__send__’).
Допускается именивание методов в стиле Smalltalk. Имеется ввиду, что если
у вас есть метод SomeClass.make_from
и он вызывается как
SomeClass.make_from file
или SomeClass.make_from :file => name
. В этом
случае имя параметра дополняет имя метода и повышает общую читабельность.
Имена переменных должны быть ясными и осмысленными (естественно, можно использовать имя ‘i’ для счетчика). Пытайтесь не перекрывать названия методов переменными, например внутри класса Array используйте ‘idx’ вместо ‘index’, поскольку последнее является именем метода.
Используйте постусловия только если ваше выражение помещается на одной строчке и у вас не очень много условий.
Блоки: Используйте или do ... end
или {...}
, а также пробелы между
разделителями и кодом (foo { |arg| code }
). Разбивайте длинные и сложные
выражения на несколько строк, примерно как в следующем случае:
mapped = foo.map do |elem|
do_something_with elem
end
Определение Module/Class с указание пространства имен:
module Rubinius::Profiler
class Sampler
end
end
Первичное требование для всего кода ядра это простота и эффективность. Простой
код зачастую более эффективен и более понятен. В коде, отвечающем за
начальную загрузку не должно быть метапрограммирования. Используйте #attr_xxx
методы внутри любых исходников ядра. Также, для задания алиасов методам
используйте #alias_method, вызываемый сразу за описанием метода. Делайте методы
приватным с помощью private :sym
сразу после описания метода. Помните,
что версии методов, описанных выше на стадии alpha принимают один символьный
аргумент.
Используйте RDoc для документирования в Ruby коде.
Используйте Doxygen для документирования в C++ коде.
Используйте Markdown для документирования в директории /doc. Смотри Синтаксис Markdown. Установите ширину текста в 78 символов и используйте жесткие переносы.