14

Are these equivalent?

class Empty : pass

and

class Empty:
    '''
    This class intentionally left blank
    '''

The second one seems better for readability and one could put pass at the end but it does not seem necessary.

Is the comment treated as a pass?

martineau
  • 119,623
  • 25
  • 170
  • 301
Ray Salemi
  • 5,247
  • 4
  • 30
  • 63
  • 3
    It's a misconception that that's a comment. Comments start with `#`. What you have there is a string. – Aran-Fey Apr 10 '18 at 13:07

2 Answers2

18

Your two codes are almost equivalent, but not quite. pass is just a no-op. The docstring is almost a no-op as well, but it adds a __doc__ attribute to your class object, so there is a small difference.

A version that would be functionally equivalent to using pass would be to use Ellipsis a.k.a. ...:

class Empty: ...

There is nothing special about ... in this case. Any pre-existing object that you don't assign will work just as well. For example, you could replace ... with None, 1, True, etc. The choice of ... is a popular alternative because it is much more aesthetically pleasing. By convention, it means a stub that is to be filled in, while pass usually indicates a deliberate no-op.

Using ... like that will raise a SyntaxError in Python 2. You can use the named Ellipsis object instead, but that is not nearly as pretty.

You may also find this question about the equivalence of pass and return None in functions interesting.

Mad Physicist
  • 107,652
  • 25
  • 181
  • 264
  • 2
    Why would you use `Ellipsis` rather than say a boolean or integer or anything else you throw away? Wouldn't `None` be most equivalent? – Chris_Rands Apr 10 '18 at 13:14
  • 2
    @Chris_Rands. No particular reason, but it's semi conventional at this point. Using a particular value implies code or a return value or something, and just generally looks wrong. Ellipsis seems to look right. I'll find a source or two for that. – Mad Physicist Apr 10 '18 at 13:22
  • You should also note that Python 2 considers using an ellipsis instead of `pass` that a `SyntaxError`—so the former is more version independent. – martineau Apr 10 '18 at 13:46
  • @martineau. Added. Interesting that `...` is an error but `Ellipsis` is not. Is it being treated like `:` outside `[]`? – Mad Physicist Apr 10 '18 at 13:52
  • I think the syntax difference is due to the fact that `Ellipsis` had a more limited role in Python 2 where it was used only for something called "extended slicing syntax" which is meaningless as a standalone statement. – martineau Apr 10 '18 at 14:10
  • Thanks, interesting, I didn't know Raymond and others were promoting this, I see the readability aspect but it's not intuitive if you know what the `Ellipsis` is actually used for normally. Also only using `None` provides equivalent Cpython bytcode to using `pass` – Chris_Rands Apr 10 '18 at 14:21
4

No, they're not equivalent.

Since the implementation of PEP 257, if the first expression in a module, function, or class is a string, that string will be assigned to that module/function/class's __doc__ attribute:

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

Functionally, the classes are equivalent. However, the difference between having a docstring and not having a docstring can surface when you're creating documentation for your code. Tools like sphinx-autodoc can pick up the docstring and generate documentation for your class, and you'll end up with something like this in your documentation:

class Empty()

This class intentionally left blank

For this reason, it's generally preferable not to use a docstring for this kind of thing. Instead, it would be better to use a comment:

class Empty:
    pass  # This class intentionally left blank
Aran-Fey
  • 39,665
  • 11
  • 104
  • 149