Статьи

.NET в Ruby: пространство имен, соглашения об именах, комментарии и документация

Ноябрь 13, 2018

Ruby — самоуверенный язык, и у него есть самоуверенное сообщество. Это отличная вещь. Он сохраняет язык чистым, понятным и веселым.

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

Пространства имен

Программы, которые мы пишем, используют пространства имен для двух целей: 1. Группировать код в связанные функциональные группы и 2. Чтобы предотвратить столкновение методов, классов, переменных и констант друг с другом. В .NET мы используем ключевое слово namespace Синтаксис пространства имен обернут вокруг кода, который вы хотите включить в пространство имен, и он содержится в открывающих и закрывающих фигурных скобках {}: 

 namespace FooBar {
    // ...
}

В Ruby module 

 module Fizz
  # ...
end

Из поста о Ruby Classes вы помните, что модули используются не только для пространств имен, они также используются для создания миксинов — ознакомьтесь с постом для более детального изучения миксинов.

Соглашения об именах

Соглашения об именах Ruby довольно легко понять. Мы рассмотрели большинство этих соглашений об именах в предыдущих постах, но о них стоит упомянуть в одном месте: 

 Type          .NET           Ruby
Namespaces    CamelCase      CamelCase
Classes       CamelCase      CamelCase
Methods       CamelCase      underscores_and_lowercase
Variables     camelBack      underscores_and_lowercase
Constants     CamelCase      ALL_CAPS

Возможно, вы знаете CamelCase по его альтернативному имени PascalCase.

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

 IMPORTANT_VALUE = 1
puts "Important Value: #{IMPORTANT_VALUE}"

IMPORTANT_VALUE = 2
# A warning is issued after the above line executes: 
#    warning: already initialized constant
puts "Important Value: #{IMPORTANT_VALUE}"

Добавьте вышеупомянутое с нотацией @instance_variable@@class_variableметодах и переменных Ruby , и вы получите большинство соглашений Ruby по именованию.

Комментарии и документация

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

 # This is a comment

Если бы мы хотели создать многострочный комментарий, мы могли бы использовать следующее: 

 =begin
  Comment goes here. =begin and =end must start
  at the left margin otherwise they are ignored.
=end

Многострочные комментарии должны использоваться в коде нечасто. Вместо этого многострочные комментарии лучше подходят для комментирования больших разделов кода во время разработки. Для больших блоков комментариев (например, в документации) использование хеша является предпочтительным.

Что касается документации, то в Ruby мне нравится то, что инструменты документации поставляются в комплекте с базовым языком через инструмент под названием RDoc. Больше не нужно искать, чтобы выяснить, следует ли вам использовать NDoc, Sandcastle, GhostDoc, Doxygen или последнюю версию месяца, и будет ли проект жить так долго, как ваш проект — RDoc существует сегодня, и он будет там завтра. Еще одна приятная особенность заключается в том, что RDoc поддерживает разметку, поэтому легко и просто написать свою документацию и прочитать ее из исходного кода, а также обработать ее в документации для Интернета. Если вам не хватает подробностей, RDoc README — отличное место.

Кроме того, базовую документацию по Ruby можно найти в Интернете по адресу http://ruby-doc.org/core . Больше не нужно искать MSDN! Документация Ruby очень полезна, и в большинстве случаев содержит краткие примеры того, как использовать тот или иной метод. Например, давайте сравним документацию C # для String.Trim () с наиболее эквивалентным методом String # strip . Я говорю в основном эквивалентно, потому что в документации .NET не ясно, удаляет ли она символы новой строки, такие как rn 

 using System;

public class Example
{
   public static void Main()
   {
      Console.Write("Enter your first name: ");
      string firstName = Console.ReadLine();

      Console.Write("Enter your middle name or initial: ");
      string middleName = Console.ReadLine();

      Console.Write("Enter your last name: ");
      string lastName = Console.ReadLine();

      Console.WriteLine();
      Console.WriteLine("You entered '{0}', '{1}', and '{2}'.",
                        firstName, middleName, lastName);

      string name = (firstName.Trim() + " " + middleName.Trim()).Trim() + " " +
                    lastName.Trim();
      Console.WriteLine("The result is " + name + ".");
   }
}
// The following is possible output from this example:
//       Enter your first name:    John
//       Enter your middle name or initial:
//       Enter your last name:    Doe
//
//       You entered '   John  ', '', and '   Doe'.
//       The result is John Doe

Что это за чудовище! Я расстроен таким примером, потому что требуется очень много работы, чтобы понять, что на самом деле происходит. Сравните это с документацией по Ruby: 

 # str.strip -> new_str
# Returns a copy of str with leading and trailing whitespace removed.
"    hello    ".strip   #=> "hello"
"tgoodbyern".strip   #=> "goodbye"

Да, это вся документация по методу для strip Вы видите, что одна из целей Ruby состоит в том, чтобы сделать этот язык забавным для программирования, и в разгар этой цели все помехи были удалены. Осталось только то, что нужно. Принимая во внимание пример C #, вы должны прочитать до 19-й строки, чтобы перейти к функции Trim() А затем вы должны разобрать скобки, кавычки и конкатенации. Blekk!

Еще одна замечательная вещь в Ruby состоит в том, что если вам не нравится документация для конкретного метода и вы думаете, что он может быть очищен, вы можете отправить патч для этой части документации. Вы видите, что Ruby позволяет кодировщикам делать что-то и отдавать, если чего-то не хватает. Когда в последний раз MS позволяла вам делать что-либо с C # и .NET, кроме как через зуб за лицензии на программное обеспечение!

Достаточно хорошо моего разглагольствования. Теперь я слышу, как вы спрашиваете, что произойдет, если я не подключен к Интернету? Как мне получить доступ ко всей этой замечательной документации? Это просто — с помощью инструмента под названием ри. ri — это встроенная в Ruby программа для просмотра документации. Допустим, вы хотите знать, какие методы доступны для String

ri String

И Ри создаст для вас все методы, которые могут быть запущены против String. Если вы хотите глубже понять, что делает метод, добавьте имя метода в его класс:

ri String # strip

Ри является отличным инструментом для изучения того, что доступно на языке, и, конечно, превосходит случайные нажатия F1 Важно отметить, что если вы используете Ruby 1.8.7, вам нужно установить rdoc-data 

 $ gem install rdoc rdoc-data
$ rdoc-data --install

Этот драгоценный камень исправляет документацию ri и делает его более полезным . Эта проблема исправлена ​​в 1.9.2, поэтому не нужно беспокоиться об этом, если вы используете эту версию.

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

В следующем посте мы сделаем глубокое погружение в систему типов Ruby и посмотрим, что происходит под капотом Ruby.

46
Share: