Написание комментариев в 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
Вы увидите вывод:
<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, в которой компьютер выдает случайный ответ на заданный вами вопрос. Обратите внимание, что комментарии имеют такие же отступы, что и код, с которым они связаны.
# 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 существует альтернативный синтаксис многострочных комментариев, но он используется редко. Он выглядит так:
=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 ставятся в начало строки. Они не требуют отступов. Именно потому такой синтаксис редко используется.
Встроенные комментарии
Встроенные комментарии находятся в одной строке с кодом, который они объясняют. Как и другие типы комментариев, они начинаются с символа #, после которого идет пробел.
Общий синтаксис встроенного комментария выглядит так:
# 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 удобочитаемыми. Наличие уместных и соответствующих коду комментариев облегчает другим пользователям работу с вашей программой. Также комментарии помогают вам понять код, который вы написали ранее, или отладить программу.
Tags: Ruby