Как использовать комментарии в Ruby

Вступление

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

Некоторые комментарии могут остаться в коде навсегда, например, те, которые объясняют контекст, в то время как другие комментарии могут быть временными, например, заметки, которые вы оставляете сами, пока создаете свою программу.

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

Комментарии в Ruby начинаются с хеш-метки (+ # +) и продолжаются до конца строки, например:

# This is a comment in Ruby

Хотя это и не требуется, вы должны поместить пробел после хеш-метки, чтобы улучшить читаемость комментария.

Когда вы запускаете программу, вы не увидите никаких признаков комментариев в коде; интерпретатор Ruby полностью их игнорирует. Комментарии содержатся в исходном коде для чтения людьми, а не для выполнения компьютерами.

В простой программе на Ruby, например, в учебнике How to Write Your First Ruby Program, вы можете использовать комментарии, чтобы дать дополнительную информацию о том, что происходит в каждой части кода:

greetings.rb

# Display a prompt to the user
puts "Please enter your name."

# Save the input they type and remove the last character (the enter keypress)
name = gets.chop

# Print the output to the screen
puts "Hi, #{name}! I'm Ruby!"

Эти комментарии дают вам общее представление о том, что делает каждый раздел программы и как она работает.

В программе, которая выполняет итерацию по массиву и отображает его содержимое в виде списка HTML, вы можете увидеть комментарии вроде этого, которые дают немного больше объяснения о том, что делает код:

sharks.rb

sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# transform each entry in the array to an HTML entity, with leading spaces and a newline.
listitems = sharks.map{ |shark| "  <li>#{shark}</li>\n"}

# Print the opening <ul>, then print the array of list items
print "<ul>\n#{listitems.join}</ul>"

Возможно, вы еще не знакомы с такими вещами, как + map + и + join +, но комментарии дают вам представление о том, как эта программа должна работать и как может выглядеть результат. Попробуйте это. Поместите этот код в файл с именем + sharks.rb + и запустите его:

ruby sharks.rb

Вы увидите вывод программы:

Output<ul>
 <li>hammerhead</li>
 <li>great white</li>
 <li>dogfish</li>
 <li>frilled</li>
 <li>bullhead</li>
 <li>requiem</li>
</ul>

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

Комментарии должны быть сделаны в том же отступе, что и код, который они комментируют. То есть определение класса без отступа будет иметь комментарий без отступа, а каждый следующий уровень отступа будет иметь комментарии, которые выровнены с кодом, который он комментирует.

Например, вот реализация Ruby для игры Magic 8-Ball. Компьютер даст случайный ответ на заданный вами вопрос. Обратите внимание, что комментарии имеют отступ с тем же уровнем отступа, что и код в каждом разделе.

magic8ball.rb

# The Eightball class represents the Magic 8-Ball.
class Eightball

 # Set up the available choices
 def initialize
     @choices = ["Yes", "No", "All signs point to yes", "Ask again later", "Don't bet on it"]
 end

 # Select a random choice from the available choices
 def shake
   @choices.sample
 end
end

def play
 puts "Ask the Magic 8 Ball your question."

 # Since we don't need their answer, we won't capture it.
 gets

 # Create a new instance of the Magic 8 Ball and use it to get an answer.
 eightball = Eightball.new
 answer = eightball.shake
 puts answer

 # Prompt to restart the game and evaluate the answer.
 puts "Want to try again? Press 'y' to continue or any other key to quit."
 answer = gets.chop

 if answer == 'y'
   play
 else
   exit
 end
end

# Start the first game.
play

Предполагается, что комментарии помогут программистам, будь то оригинальный программист или кто-то еще, кто использует или сотрудничает в проекте. Это означает, что комментарии должны поддерживаться так же, как код. Комментарий, который противоречит коду, хуже, чем вообще никакой комментарий.

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

Например, комментарии такого рода не будут полезны, если вы знаете Ruby:

# print "Hello Horld" to the screen.
print "Hello World"

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

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

Вы можете использовать блочные комментарии, чтобы объяснить более сложный код или код, который, как вы ожидаете, не будет знаком читателю. Эти комментарии более длинной формы применяются к части или всему следующему коду, а также имеют отступ на том же уровне, что и код.

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

Ниже приведен пример блочного комментария из исходного кода веб-платформы Sinatra. Он предоставляет некоторый контекст другим разработчикам о том, как работает этот конкретный код:

https://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb

...
 # Some Rack handlers (Thin, Rainbows!) implement an extended body object protocol, however,
 # some middleware (namely Rack::Lint) will break it by not mirroring the methods in question.
 # This middleware will detect an extended body object and will make sure it reaches the
 # handler directly. We do this here, so our middleware and middleware set up by the app will
 # still be able to run.
 class ExtendedRack < Struct.new(:app)
   def call(env)
     result, callback = app.call(env), env['async.callback']
     return result unless callback and async?(*result)
     after_response { callback.call result }
     setup_close(env, *result)
     throw :async
   end
...

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

У Ruby есть альтернативный синтаксис для многострочных комментариев, но он используется редко. Вот пример:

multiline.rb

=begin
This is a multi-line comment.
You can use this approach to make your comments
span multiple lines without placing hash marks at the start of each
line.
=end

Строки + = begin и` + = end` должны находиться в начале строки. Они не могут быть с отступом. По этой причине вы редко увидите, как это используется.

Давайте посмотрим на встроенные комментарии дальше.

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

Как правило, встроенные комментарии выглядят так:

[code]  # Inline comment about the code

Встроенные комментарии следует использовать с осторожностью, но они могут быть эффективны для объяснения хитрых или неочевидных частей кода. Они также могут быть полезны, если вы считаете, что не помните ни одной строки кода, которую вы пишете в будущем, или если вы сотрудничаете с кем-то, кого вы знаете, возможно, не знакомы со всеми аспектами кода.

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

a=Complex(4,3) # Create the complex number 4+3i

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

pi = 3.14159 # Intentionally limiting the value of pi for this program.

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

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

Например, в игре Magic 8-Ball вы, возможно, хотите запретить повторный запуск игры, потому что вы просто заинтересованы в том, чтобы код правильно оценивал ответ. Вы можете просто закомментировать строку кода, которая снова запускает игру:

8ball.rb

...

 # Prompt to restart the game and evaluate the answer.
 puts "Want to try again? Press 'y' to continue or any other key to quit."
 answer = gets.chop

 if answer == 'y'
   # play
 else
   exit
 end
end
...

Комментарии также позволяют вам попробовать альтернативы, пока вы определяете, как реализовать решение в своем коде. Например, вы можете попробовать несколько разных подходов при работе с массивами в Ruby. Вы можете использовать комментарии, чтобы протестировать каждый подход и определить, какой вам нравится больше всего:

sharks.rb

sharks = ["Tiger", "Great White", "Hammerhead"]

# for shark in sharks do
#  puts shark
# end

sharks.each do |shark|
 puts shark
end

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

Заключение

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

TOC

Как использовать комментарии в Ruby

Вступление

Заключение

Related