34

Most languages allow block comments, and multiline commands.

For example, a multiline comment in HTML looks like the following:

<!-- 
Warning, brave programmer:
Here be dragons.
-->

In Elixir, the closest thing I have found comes from EEx (docs).

EEx smartengine <% #comments %> seem to be discarded from source, even if they are multiline. However, this is just a workaround.

Does Elixir have a multiline comment feature, or a way to instruct the compiler to discard text from the compiled .beam file?

3
  • 1
    Is there some issue with using the # on multiple lines? Lots of editors have support for automatic insertion of comment characters at the beginning of a set of marked lines. Commented Jun 11, 2015 at 13:34
  • 1
    Sometimes when you commit code, you might not want to change the commit history of specific lines, at least for my use case.
    – owyongsk
    Commented Sep 5, 2017 at 5:56
  • // , No issue, it's just a question Commented Aug 6, 2018 at 18:11

5 Answers 5

36

Elixir does not have multiline comments.

However, one very common use case for multiline comments is documenting modules and functions, for which you can use the module attributes @doc and @moduledoc together with heredocs.

defmodule MyModule do
  @moduledoc """
  This module is great at X
  """

  @doc """
  Frobnicates the given string.
  """
  def frobnicate(s) do
  end
end
10
  • 1
    // , Actually, I didn't want to put this in the question since I get accused of being long winded a lot, but I'm trying to convert my projects over to the Literate Programming technique. I'm told I have a rather odd way of going about things, and I will not be the one maintaining my project. A sort of intermediate step in this conversion will, I suspect, involve massive strings that I would rather not have end up in my .beams. Do the @moduledoc and @doc end up in compiled code? Do Literate Programming tools exist that use Elixir-lang? Commented Jun 10, 2015 at 7:16
  • 1
    I need to clarify the thing with module attributes: "normal" module attributes do not end up in the BEAM file. The special ones listed in the documentation also are discarded, but they are used to generate documentation, which in turn ends up in the BEAM file. Commented Jun 10, 2015 at 7:54
  • 1
    I think using module attributes to do literate programming feels wrong. I am quite sure that comments do not end up in the BEAM file, they are discarded by the tokenizer. See this recent question: stackoverflow.com/questions/30543321/… Commented Jun 10, 2015 at 8:06
  • 8
    There is some confusion here. The documentation is stored in the BEAM file but it is not loaded when the module code is loaded. It is stored in a special chunk, which is loaded only when needed, similar to how the abstract code is stored. Other than that, attributes aren't stored in the BEAM file too, unless explicitly configured. Commented Jun 10, 2015 at 13:29
  • 2
    You'll probably want to use @moduledoc ~S""" and @doc ~S""" to avoid interpolation. Commented Jan 5, 2016 at 20:14
18

I try to just use """ to quickly comment code a la Python, without turning it into a documentation

"""
def some_function() do
  some_code    
end
"""
6
  • 2
    // , Ah, but does it end up in the .beam file? Commented Sep 6, 2017 at 18:39
  • 1
    I'm gonna go on a BEAM rabbit hole now, will report back.
    – owyongsk
    Commented Sep 7, 2017 at 4:42
  • 5
    This gives a warning warning: code block contains unused literal "THESE ARE COMMENTS\n" (remove the literal or assign it to _ to avoid warnings) Commented Dec 1, 2017 at 10:04
  • 2
    @mraaroncruz would assigning _ = """ work to not show those warnings?
    – owyongsk
    Commented Dec 4, 2017 at 2:45
  • @owyongsk yep that works for me. It's hacky, but seems to satisfy credo
    – Taryn East
    Commented Aug 5, 2021 at 0:11
14

Macros could help here to some degree:

defmodule Comment do
  defmacro comment(_text) do
  end
end

defmodule TestComment do
  import Comment

  comment """
  Module
  Comment
  """

  def func do
    comment """
    Function
    Comment
    """
  end
end
5
  • // , This does not seem as 'proper' an answer as using the @moduledoc and @doc, but it answers the specific question more directly. Commented Feb 16, 2016 at 0:02
  • // , Would this text be present in the BEAM file? Commented Feb 16, 2016 at 0:03
  • 4
    @NathanBasanese: the text is discarded by the macro, so it won't even be in the AST after macro processing. So no, it will not make it into the BEAM file.
    – Dimagog
    Commented Dec 16, 2016 at 20:42
  • // , Given that this will not end up in the .beam file, I'm liking this answer a bit more. For the curious, "AST" in the above comment refers to an "Abstract Syntax Tree". You can search in the page at the following link for Abstract Syntax Tree for a good bit of context beyond the generic WikiPedia article. #nocsdegree Commented Dec 17, 2016 at 5:16
  • 2
    docp and doc generate warnings by the compiler. I think this is by far the best solution. It's just not standard practice. Commented Feb 2, 2017 at 15:32
9

You can simply use module attributes for multiline comments, no macro required. I typically use the following for documenting/commenting private functions:

@docp """
This is my
multi line
comment
"""
4
  • 2
    This has to be the absolutely simplest and cleanest way of doing multiline comments! Commented Feb 4, 2017 at 9:03
  • 4
    warning: module attribute @docp was set but never used Commented Jun 23, 2017 at 8:10
  • Yes, you're right. I think that started in Elixir 1.4.x so I no longer use that strategy for the same reason. I'm back to mostly using comments. Although in a few cases I have actually created a macro called docp that compiles to nothing.
    – Kip
    Commented Jun 24, 2017 at 9:09
  • 2
    How about just """ without the @docp?
    – owyongsk
    Commented Sep 5, 2017 at 5:58
2

I know I'm late and that this question has already been answered, but I found a way that works, using a sigil that prevents string interpolation. I figured I could share it for others who stumble upon this post.

~S"""
Hi! 
I'm a
multiline comment!
"""

This works in modules and functions too, including if it is the last thing in the block. Unlike regular string literals (i.e. without the ~s sigil prepended to it), this does not throw an error or warning.

Keep in mind that this is not an official language feature. Out of the box, Elixir only supports single-line comments (# Comment) and the module documentation syntax (@moduledoc / @doc).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.