Как записать значимые docstrings?
Используйте dynamic_cast для преобразования указателей / ссылок в иерархию наследования.
Используйте static_cast для конверсий обычного типа.
Используйте reinterpret_cast для низкоуровневого переинтерпретации бит. Используйте с особой осторожностью.
Используйте const_cast для отбрасывания const/volatile. Избегайте этого, если вы не застряли, используя API-интерфейс с константой.
5 ответов
Я соглашаюсь с "Чем-либо, что Вы не можете сказать от подписи метода". Это могло бы также означать объяснять, что возвращает метод/функция.
Вы могли бы также хотеть использовать Сфинкс (и reStructuredText синтаксис) в целях документации в Ваших docstrings. Тем путем можно включать это в документацию легко. Поскольку пример проверяет, например, repoze.bfg, который использует это экстенсивно ( пример документации файла , в качестве примера ).
Другая вещь можно вставить docstrings, также doctests. Это могло бы иметь смысл особенно для модуля или docstrings класса, поскольку можно также показать, что путь, как использовать его и иметь это тестируемое одновременно.
От PEP 8:
Конвенции для записи хороших строк документации (иначе "docstrings") увековечены в PEP 257.
- docstrings Записи для всех общедоступных модулей, функций, классов и методов. Docstrings не необходим для непубличных методов, но у Вас должен быть комментарий, который описывает то, что делает метод. Этот комментарий должен появиться после строки "определения".
- PEP 257 описывает хорошие docstring конвенции. Обратите внимание, что самое главное," "" который заканчивает мультилинию, docstring должен быть на строке отдельно, и предпочтительно предшествовавший пустой строкой.
- Для docstrings лайнера, это должно хорошо сохранить закрытие" "" на той же строке.
Самыми поразительными вещами, о которых я могу думать для включения в docstring, являются вещи, которые не очевидны. Обычно это включает информацию о типе, или требования возможности - например, "Требуют подобного файлу объекта". В некоторых случаях это будет очевидно из подписи, не так в других случаях.
Другая полезная вещь, которую можно вставить к docstrings, doctest.
Что должно пойти туда:
Что-либо, что Вы не можете сказать от подписи метода. В этом случае единственный полезный бит: displayName - если пустой будет установлен на имя поля.
Мне нравится использовать документацию для описания в как можно большем количестве деталей, что функция делает, особенно поведение в угловых случаях (иначе пограничные случаи). Идеально, программисту, использующему функцию, никогда не придется смотреть на исходный код - на практике, который означает что каждый раз, когда другой программист действительно должен посмотреть на исходный код для выяснения некоторой детали того, как функция работает, что деталь, вероятно, должна была быть упомянута в документации. Как Freddy сказал, что-либо, что не добавляет, что любая деталь к подписи метода, вероятно, не должна быть в строке документации.