Почему я должен использовать комментарии при документировании Python?

Question

Существует два способа документировать модуль, функцию или класс в самом коде: comments и docstrings.

Docstrings более функциональны, так как к ним можно получить доступ через функцию help(), тогда как comments можно получить только в исходном коде.

Когда следует использовать комментарии вместо docstrings?

Answer 1

Строки документов предназначены для объяснения того, что функция делает , с точки зрения того, какие виды и типы значений она принимает и возвращает, с точки зрения пользователя.

Комментарии, с другой стороныНаходясь в теле исходного кода, будет виден только тем, кто действительно его читает, и, соответственно, служит для объяснения как делает то, что делает.