Документация/коменты в Django?

Question

[zelsky]

Есть ил какой стайлгайд как правильно коментировать классы и что туда писать ? Делали мне код ревью, так вот пример коментария, как примерно понятно. Но если стайл гайд ?

"""
        Check if current user role matches to given.
        @:param role: user role.
        @:type role: int.
        @:rtype bool.
        @:return True if user matches given role. Else returns false.
        """

Answer 1

[Roman K]

Есть стайлгайды и форматы.
Официальный гайд: PEP 257

Всё остальное, что там есть - это удобства для IDE. Твой формат первый раз вижу, обычно используют reST для PyCharm.

"""
Описание, что делает метод/функция

:param param1: Что за параметр принимается
:param param2: Ещё один параметр, который принимается
:returns: Какое значение возвращается
:raises KeyError: В каком случае рейзится эта ошибка
"""

Всё это имеет смысл, есть проект реально большой и его планируется поддерживать целым табором и долгое время. В другом случае - это пустая трата времени.

Comments

[zelsky]

Ко мне проект уже попал легаси без коментариев и тестов. А проекту то уже 2года как Джанго 1.8.4 Потому и думаю свою работу делать на отлично, ибо за 2 года проект только дошел до стадии бета. Спасибо во всяком случае.

[zelsky]

Прочитал твою статью когда толстый .... чувак, у меня в главно апп вью на 700 строк. пздц

Answer 2

[Сергей Горностаев]

PEP257