Комментарии кодов Python

В C # и через Visual Studio можно прокомментировать ваши функции, чтобы вы могли рассказать, кто использует ваш класс, какие входные аргументы должны быть, что он должен возвращать и т. Д. Есть ли что-то отдаленно похожее на python?

Я думаю, что вы получаете то, что у C # есть сильная культурная конвенция для форматирования комментариев кода, а Visual Studio предоставляет инструменты, которые собирают эти комментарии вместе, форматируют их в соответствии с согласованной разметкой и т. Д. Java похож, с его Javadoc.

У Python есть такие соглашения, как это, но они не такие сильные. PEP 257 охватывает лучшие практики, и такие инструменты, как Sphinx, хорошо собирают их вместе для подготовки документации.

Как объяснили другие ответы, docstrings являются первой строкой в ​​модуле, классе или функции. Лексически это просто строка (обычно трижды цитированная для многострочной документации), но они сохраняются как атрибут __doc__ объекта и поэтому доступны для легкой интроспекции с помощью инструментов.

В Python вы используете docstrings следующим образом:

 def foo(): """ Here is the docstring """ 

В основном вам нужно, чтобы строка с тройным цитированием была в первой строке функции, класса или модуля, чтобы считаться docstring.

Примечание. На самом деле, вам не нужно использовать строку с тройным цитированием, но это соглашение. Любая литерная строка будет делать, но лучше придерживаться соглашения и использовать тройную кавычку.

Как упоминалось в других ответах, строка в самой верхней части функции служит в качестве документации:

 >>> def fact(n): ... """Calculate the factorial of a number. ... ... Return the factorial for any non-negative integer. ... It is the responsibility of the caller not to pass ... non-integers or negative numbers. ... ... """ ... if n == 0: ... return 1 ... else: ... return fact(n-1) * n ... 

Чтобы просмотреть документацию для функции в интерпретаторе Python, используйте help :

 >>> help(fact) Help on function fact in module __main__: fact(n) Calculate the factorial of a number. Return the factorial for any non-negative integer. It is the responsibility of the caller not to pass non-integers or negative numbers. (END) 

Многие инструменты, которые генерируют HTML-документацию из кода, используют первую строку в качестве сводки функции, а остальные строки содержат дополнительные сведения. Таким образом, первая строка должна быть короткой, чтобы хорошо вписываться в списки функций в сгенерированной документации.

Просто поставьте строку в любом месте. Если в методе есть первая строка, Python поместит ее в специальное поле __doc__ :

 def f(): """This is the documentation""" pass """But you can have as many comments as you like.""" print f.__doc__