Multi-line comments use `#` or `#=`?

[mattBrzezinski]

Looking at the guide I came across this example:

# Yes:

# Number of nodes to predict. Again, an issue with the workflow order. Should be updated
# after data is fetched.
p = 1

# No:

p = 1  # Number of nodes to predict. Again, an issue with the workflow order. Should be
# updated after data is fetched.

What are peoples thoughts on this style:

#=
Number of nodes to predict. Again, an issue with the workflow order. Should be
updated after data is fetched. 
=#
p = 1

[nickrobinson251]

i don't think we take a stance on that currently - do you think we should?

if we were summing up what we do in practice I think it is:

• prefer commenting each line with # rather than using #= =#
• #= =# can be used in the rare case you need very long comment blocks e.g. > 5 lines
• do not use #= =# inside code blocks, e.g. inside a function or struct

[mattBrzezinski]

I just noticed we didn't cover it in this style guide, and its bound to come up at some point.

I think your summary makes sense!

[oxinabox]

do not use #= =# inside code blocks, e.g. inside a function or struct

Why?

I am guessing reasoning is that if a function needs that much comment it should have been multiple functions?

idk some things are hard.

[omus]

I tend to use #= =# only for commenting out code as doing so makes viewing diffs less noisy

[oxinabox]

Oh is that what you are doing there

[iamed2]

I don't think we should take a stance on this. TBH I think the reason we don't use block comments as much is because they arrived later, and because Python and MATLAB both don't have them.

[JeffFessler]

Actually Matlab does have block comments using %{ and %} https://www.mathworks.com/help/matlab/matlab_prog/comments.html They are quite useful both for commenting out code blocks and for making "longer" comments more readable. But "longer" should be left to the eye of the beholder (or coder).

[iamed2]

Actually Matlab does have block comments

😮