Григорий Петров (Digital October)
В своем докладе Григорий расскажет о том, как и что комментировать в исходном коде ваших программ, чтобы комментарии принесли максимальную пользу.
Users.find( user ).banned = True Что можно сделать: def ban_user( user ): Users.find( id = user ).banned = True def ban_user( user_id ): Users.find( user_id ).banned = True def ban_user( user ): Users.findById( user ).banned = True
пока не потеряет поддерживаемость. Информация отдельно от кода Документы начинают пухнуть, пока не потеряют поддерживаемость. Из этих наблюдений мы делаем промежуточный вывод: с ростом проекта, если мы будем класть информацию для человека в любое одно место, это место начнет пухнуть, а проект - дохнуть.
куда класть исходники. Там была точно такая же проблема: с ростом проекта, чтобы сохранить поддерживаемость, мы размазывали сложность по уровням абстракции.
компилятора. Человеку, чтобы не потеряться, нужны маяки для навигации. • Маяки можно расставлять разными способами: самим кодом, комментариями, в коммитах, в документации.
дублирует уже имеющуюся в коде информацию. Не отвечает на вопрос “зачем?”. # Первый пользователь по умолчанию админ. user.role = 4 Отвечает на вопрос “зачем”. Но можно еще лучше: # Первый пользователь. user.role = USER_ROLE_ADMIN
Поменял пару строк Багфикс А что было бы полезно: Добавлен по ошибке, не нужен. Сделал имена контейнеров понятнее #ref 1963: пытаемся понять, почему падает #fix 1963
- ничего не делаем. 2. Если можно добавить информацию в сам код и он не лопнет - добавляем. 3. Если можно добавить информацию в документацию так, чтобы она не лопнула и не потеряла связь с действительностью через месяц, - добавляем. 4. Если ничего из вышеописанного не получается - пишем комментарий, отвечающий на вопрос “зачем?”. Пишем только то, чего нет в самом коде. Логически завершенные части кода коммитим, снабжая коммит комментарием, отвечающим на вопрос “зачем?”.