В каких случаях используется docstring, а в каких — комментарий?

Docstring и комментарии имеют разные цели и предназначены для разных аудиторий. writing.stackexchange.com

Docstring (строка документации) используется для описания назначения функций, классов, модулей или методов. {8-host} Он помогает разработчикам понять, как использовать код, не вникая в его реализацию. {8-host} Docstring предназначен для людей, которые собираются использовать код, не интересуясь, как он работает. writing.stackexchange.com stackoverflow.com

Комментарии в коде — это текстовые заметки, которые программист оставляет внутри кода, чтобы объяснить его работу или добавить важные пояснения. {9-host} Комментарии не влияют на выполнение программы, они предназначены исключительно для людей, работающих с кодом. {9-host}

Некоторые случаи, в которых используется комментарий:

• Информативные комментарии. nuancesprog.ru Например, объяснение возвращаемого значения функции помогает лучше понять процесс, особенно в сложных случаях. nuancesprog.ru
• TODO-комментарии. nuancesprog.ru Они указывают на незавершённые задачи или области, требующие доработки. nuancesprog.ru
• Предупреждения о последствиях. nuancesprog.ru Некоторые сегменты кода могут быть связаны с такими рисками, как, например, проблемы с производительностью или потенциальные ошибки. nuancesprog.ru
• Разъяснение сложных алгоритмов. nuancesprog.ru Некоторые алгоритмы или логика слишком запутанны, чтобы их можно было сразу понять, даже при наличии корректно названных переменных и функций. nuancesprog.ru
• Комментарии по юридическим вопросам/соответствию. nuancesprog.ru В некоторых случаях код должен соответствовать определённым юридическим требованиям, стандартам соответствия или нормативным предписаниям. nuancesprog.ru Комментарии могут описать эти требования, указывая на ограничения или требования, которым соответствует код. nuancesprog.ru