Как использовать комментарии в Ruby
Введение
Комментарии — это строки в компьютерных программах, которые игнорируются компиляторами и интерпретаторами. Вы можете использовать комментарии, чтобы сделать ваши программы более понятными для других программистов, используя их для предоставления большего контекста или объяснения того, что делает каждая часть программы. Кроме того, вы можете использовать комментарии, чтобы объяснить, почему вы выбрали конкретное решение, или даже предотвратить временное выполнение проблемной или незавершенной части вашей программы, пока вы работаете над исправлением.
Некоторые комментарии могут оставаться в коде навсегда, например поясняющие контекст, в то время как другие комментарии могут быть временными, например заметки, которые вы оставляете сами, пока создаете свою программу.
Давайте посмотрим, как использовать комментарии в программах на Ruby для оставления заметок, а также как использовать их в качестве инструмента отладки.
Синтаксис и использование комментариев
Комментарии в Ruby начинаются с решётки (#) и продолжаются до конца строки, например:
# This is a comment in Ruby
Хотя это и не требуется, вы должны поместить пробел после решётки, чтобы улучшить читабельность комментария.
Когда вы запускаете программу, вы не увидите никаких указаний на комментарии в коде; интерпретатор Ruby полностью их игнорирует. Комментарии в исходном коде предназначены для чтения людьми, а не для выполнения компьютерами.
В простой программе на Ruby, например в учебнике «Как написать свою первую программу на Ruby», вы можете использовать комментарии, чтобы дать дополнительные сведения о том, что происходит в каждой части кода:
# 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 = ['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>
Обратите внимание, что вы не видите комментарии, так как интерпретатор их проигнорировал. Но результат, вероятно, соответствовал тому, что вы ожидали. Комментарии — отличный инструмент общения, особенно когда человек, читающий комментарии, не знаком с языком.
Комментарии должны быть сделаны с тем же отступом, что и код, который они комментируют. То есть определение класса без отступа будет иметь комментарий без отступа, и каждый последующий уровень отступа будет иметь комментарии, выровненные с кодом, который он комментирует.
Например, вот реализация игры Magic 8-Ball на Ruby. Компьютер даст случайный ответ на заданный вами вопрос. Обратите внимание, что отступ комментариев соответствует тому же уровню отступа, что и код в каждом разделе.
# 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. Он предоставляет другим разработчикам некоторый контекст о том, как работает этот конкретный код:
...
# 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 есть альтернативный синтаксис для многострочных комментариев, но он редко используется. Вот пример:
=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 вы, возможно, хотите предотвратить повторный запуск игры, потому что вам просто нужно убедиться, что код правильно оценивает ответ. Вы можете просто закомментировать строку кода, которая снова запускает игру:
...
# 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 = ["Tiger", "Great White", "Hammerhead"]
# for shark in sharks do
# puts shark
# end
sharks.each do |shark|
puts shark
end
Комментирование кода позволяет опробовать различные методы программирования, а также помогает найти источник ошибки путем систематического комментирования и запуска частей программы.
Заключение
Использование комментариев в ваших программах на Ruby может сделать программы более понятными для людей, в том числе для вас самих в будущем. Включение соответствующих комментариев, которые важны и полезны, облегчает другим пользователям сотрудничество с вами в проектах программирования. Они также помогут вам понять код, который вы написали в будущем, когда вы вернетесь к своему проекту после длительного периода времени.