Komentarze wieloliniowe w Rubim?

Jak mogę komentować wiele linii w Ruby?

#!/usr/bin/env ruby

=begin
Every body mentioned this way
to have multiline comments.

The =begin and =end must be at the beginning of the line or
it will be a syntax error.
=end

puts "Hello world!"

<<-DOC
Also, you could create a docstring.
which...
DOC

puts "Hello world!"

"..is kinda ugly and creates
a String instance, but I know one guy
with a Smalltalk background, who
does this."

puts "Hello world!"

##
# most
# people
# do
# this


__END__

But all forgot there is another option.
Only at the end of a file, of course.

• Tak to wygląda (poprzez zrzut ekranu) - w przeciwnym razie trudno będzie zinterpretować, jak będą wyglądały powyższe komentarze. Kliknij, aby powiększyć :

=begin
My 
multiline
comment
here
=end

Pomimo istnienia =begini =end, normalnym i bardziej poprawnym sposobem komentowania jest użycie #w każdym wierszu. Jeśli przeczytasz źródło dowolnej biblioteki ruby, zobaczysz, że w ten sposób komentarze we wszystkich wierszach są wykonywane prawie we wszystkich przypadkach.

#!/usr/bin/env ruby

=begin
Between =begin and =end, any number
of lines may be written. All of these
lines are ignored by the Ruby interpreter.
=end

puts "Hello world!"

Używając albo:

= początek
To
jest
za
komentarz
blok
= koniec

lub

# To
# jest
# a
# komentarz
# blok

są jedynymi dwoma obecnie obsługiwanymi przez rdoc, co jest dobrym powodem, aby używać tylko tych, jak sądzę.

=begin
(some code here)
=end

i

# This code
# on multiple lines
# is commented out

oba są poprawne. Zaletą pierwszego typu komentarza jest możliwość edytowania - łatwiej jest odkomentować, ponieważ usuwa się mniej znaków. Zaletą drugiego rodzaju komentarza jest czytelność - czytając kod wiersz po wierszu, znacznie łatwiej jest stwierdzić, że dany wiersz został skomentowany. Zadzwoń, ale zastanów się, kto będzie za tobą i jak łatwo jest je czytać i utrzymywać.

Oto przykład :

=begin 
print "Give me a number:"
number = gets.chomp.to_f

total = number * 10
puts  "The total value is : #{total}"

=end

Wszystko, co umieścisz pomiędzy =begini =endbędzie traktowane jako komentarz bez względu na to, ile wierszy kodu zawiera pomiędzy.

Uwaga: Upewnij się, że nie ma spacji między =i begin:

• Poprawny: =begin
• Źle: = begin

=begin comment line 1 comment line 2 =end upewnij się, że = początek i = koniec to pierwsza rzecz w tym wierszu (bez spacji)

Jeśli ktoś szuka sposobu na komentowanie wielu linii w szablonie HTML w Ruby on Rails, może wystąpić problem z = start = koniec, na przykład:

<%
=begin
%>
  ... multiple HTML lines to comment out
  <%= image_tag("image.jpg") %>
<%
=end
%>

zakończy się niepowodzeniem z powodu%> zamknięcia tagu obrazu.

W tym przypadku może być dyskusyjne, czy to komentuje, czy nie, ale wolę dołączyć niepożądaną sekcję blokiem „jeśli fałszywy”:

<% if false %>
  ... multiple HTML lines to comment out
  <%= image_tag("image.jpg") %>
<% end %>

To zadziała.

  def idle
    <<~aid
    This is some description of what idle does.

    It does nothing actually, it's just here to show an example of multiline
    documentation. Thus said, this is something that is more common in the
    python community. That's an important point as it's good to also fit the
    expectation of your community of work. Now, if you agree with your team to
    go with a solution like this one for documenting your own base code, that's
    fine: just discuss about it with them first.

    Depending on your editor configuration, it won't be colored like a comment,
    like those starting with a "#". But as any keyword can be used for wrapping
    an heredoc, it is easy to spot anyway. One could even come with separated
    words for different puposes, so selective extraction for different types of
    documentation generation would be more practical. Depending on your editor,
    you possibly could configure it to use the same syntax highlight used for
    monoline comment when the keyword is one like aid or whatever you like.

    Also note that the squiggly-heredoc, using "~", allow to position
    the closing term with a level of indentation. That avoids to break the visual reading flow, unlike this far too long line.
    aid
  end

Zauważ, że w momencie ogłoszenia silnik stackoverflow nie wyświetla poprawnie kolorowania składni. Testowanie, jak renderuje się w wybranym edytorze, jest ćwiczeniem. ;)