1

I had a question about docstring standard. The link: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html has been quite useful but it says that writing the docstring for the init method in a Python class can be done both under the class header or the init header. I was wondering what people's thoughts are on this i.e. pros and/or cons of doing it one way or the other.

Sergei Wallace
  • 1,129
  • 4
  • 16
  • 26
  • I think this is primarily opinion based question. Just put it where it helps you the most. Me, if the `__init__` doesn't do anything extraordinary would put it in the class documentation, because then you can easily see it with other details using `print ClassName.__doc__`. – Anshul Goyal Feb 13 '15 at 06:04
  • possible duplicate of [What is the standard Python docstring format?](http://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format) – Ozgur Vatansever Feb 13 '15 at 06:11
  • 1
    You generally call the `__init__` method calling the class, hence why it is suggested to put it here. You want to document how a class instance has to be created. There is also the `__new__` method for that. Putting the docstring under the method instead of the class means that a user has to know which method is called in order to find its docstring via `Class.__init__.__doc__`. So you are making it harder to find that information. Note that built-ins put that information on the class, probably for this reason. By the way: you can document both if you want to... – Bakuriu Feb 13 '15 at 06:55

2 Answers2

2

The docstring for the any method should appear directly below the method definition. So I think the docstring for init method also should appear below its definition.

venky
  • 21
  • 4
1

It is all a matter of opinion. There is no pros or cons of one method over the other. In my opinion the docstring for init should come under the init method as it is better to separate the init docstring from the class docstring.

Syed Suhail Ahmed
  • 685
  • 5
  • 20