""" vs #= =# comment


#1

I always thought that

"""
Test
"""

is the same as

#=
Test
=#

But it looks like """ is only used in front of functions to document them, correct?

I realized this as I found out that

"""
    Test
"""

"""
    Test 2
"""
println("Test")

produces as error which seems weird to me.

It looks like julia tries to interpret the Test2 line which in my opinion shouldn’t be the case as this is a comment.

What are your opinions on this?

P.S. Please change the category if this isn’t the correct one :wink:


#2

Please read
https://docs.julialang.org/en/latest/manual/documentation/


#3

As far as I understand it: """ is used for documentation of methods, macros etc.
Therefore using """ as I did should be bad practice :smiley: Anyway I don’t really get why it produces an error.


#4

""" is used for multiline strings.

julia> myvar = """
       hello
       my friend
       """
"hello\nmy friend\n"

so its not a comment. Writing a string (multiline or not) before a function definition tells julia that this string is the documentation for this function

julia> "This is foo" foo(x) = x^2
foo

help?> foo
search: floor pointer_from_objref OverflowError RoundFromZero FileMonitor functionloc StackOverflowError @functionloc Factorization OutOfMemoryError

  This is foo

So my point is that, no, it is not a comment. do not use strings to write comments.


#5

Ah okay. Thanks for making this clear!


#6

IMO that page should at least make a mention of (single- or multi-line) comments. Perhaps in one of those note boxes?


#7

I am not convinced about this. Comments and docstrings are distinct concepts, one is part of the source, the other is a value associated with objects.


#8

My point exactly. They are distinct, but it’s possible for people to mix up the concepts. A small note would help make the distinction clearer IMO.


#9

There was at least one person who was confused by this…


#10

Slightly off-topic, but I have been thinking about this and related issues in light of recent questions.

When learning a new computer language, my expectation is that I need to read about 200–300 pages of documentation (hopefully a single document, but it might be all over the place). I usually just skim through some parts that I am not immediately interested in, but it is good to know about concepts that exist in the language and I can go back to them. This takes me a couple of days (I work through examples), but prevents a lot of confusion later on.

The current manual (without stdlib and devdocs) is about 120K words, roughly 200 pages with 600 words/page (lower range for textbooks and manuals, some go higher). If many people who read this are still confused about something, then the documentation clearly needs to be improved, or possibly the syntax/semantics need to be redesigned. However, my expectation is that confusion which arises before reading the documentation is an issue that needs to be remedied by the user, not the developers or the authors of the docs.


#11

As a Julia-by-the-manual user at the moment: a search for “comment” in the online Julia manual gave no heading or section in the results that even mentions comment syntax. If it is there, it is poorly discoverable (at least by me).

In addition, there doesn’t appear to be a section on the Julia language syntax. This is where I usually look to find information on comments.


Struct field change bug - can't understand why?
#12

If you search comment, then one of the sections suggested is the Punctuation section, which does tell you how to do multiline comments. Although it doesn’t tell you how to do multiline strings, which is possibly an omission?


#13

Apparently my problem was that I was looking at “Latest” and not “Stable” or “0.6.2”. Definitely discoverable there. Thanks!