Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Комментирование исходников

Комментирование исходников

Григорий Петров (Digital October)
В своем докладе Григорий расскажет о том, как и что комментировать в исходном коде ваших программ, чтобы комментарии принесли максимальную пользу.

Moscow Python Meetup

December 10, 2013
Tweet

More Decks by Moscow Python Meetup

Other Decks in Programming

Transcript

  1. Зачем нужны комментарии? • Некоторые программисты считают, что они на

    фиг не нужны. • Другие считают, что они очень нужны.
  2. Зачем нужны комментарии? • Некоторые программисты считают, что они на

    фиг не нужны. • Другие считают, что они очень нужны. • Третьи, как обычно, считают, что истина где-то посередине.
  3. Зачем нужны комментарии? Поэтому, чтобы ответить на вопрос, как лучше

    комментировать исходники, я вначале попробую ответить на вопрос, зачем их вообще комментировать.
  4. Complexity problem Обеспечивает нам радость и счастье, когда мы хотим

    поменять код. И в какой-то момент понимаем, что дешевле переписать все, чем внести нужное изменение.
  5. Complexity problem Что мы о ней знаем? • Чем больше

    кода, тем она толще. • Питается костылями и техническим долгом.
  6. Complexity problem Чем опасна? Мы хотим внести изменение, но не

    можем быстро разобраться, где менять и как менять.
  7. Complexity problem Чем опасна? Мы хотим внести изменение, но не

    можем быстро разобраться, где менять и как менять. Честно говоря, зачастую и медленно разобраться не получается :(
  8. И как такое получается? Код сам по себе информация. Много

    информации. Очень много информации. В какой-то момент мы не можем удерживать весь объем информации в голове.
  9. И как такое получается? Код сам по себе информация. Много

    информации. Очень много информации. В какой-то момент мы не можем удерживать весь объем информации в голове. И тонем :(
  10. Как можно расставлять маяки? Есть много способов. Чаще всего информацию

    добавляют: • В сам код • В документацию • В комментарии • В комментарии к коммитам
  11. Добавление информации в код Код - это информация для компилятора

    (здесь и далее - для интерпретатора тоже). В целом несложно так модифицировать код, чтобы он содержал еще и маяки для человека.
  12. Добавление информации в код Исходный фрагмент: def ban_user( user ):

    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
  13. Добавление информации в код Апологеты этого подхода считают, что лучший

    комментарий - это сам код. Зверушка, увы, так не считает. © Electronic Arts
  14. Наблюдаем две крайности Информация в самом коде Код начинает пухнуть,

    пока не потеряет поддерживаемость. Информация отдельно от кода Документы начинают пухнуть, пока не потеряют поддерживаемость.
  15. Наблюдаем две крайности Информация в самом коде Код начинает пухнуть,

    пока не потеряет поддерживаемость. Информация отдельно от кода Документы начинают пухнуть, пока не потеряют поддерживаемость. Из этих наблюдений мы делаем промежуточный вывод: с ростом проекта, если мы будем класть информацию для человека в любое одно место, это место начнет пухнуть, а проект - дохнуть.
  16. Еще наблюдаем аналогию На одной из предыдущих лекций я рассказывал,

    куда класть исходники. Там была точно такая же проблема: с ростом проекта, чтобы сохранить поддерживаемость, мы размазывали сложность по уровням абстракции.
  17. Еще наблюдаем аналогию информация для компилятора достаточно одного файла много

    файлов модули независимые проекты информация для человека достаточно самого кода в коде в комментариях в коммитах в документации рост сложности
  18. Не прошло и получаса Промежуточные выводы: • Код - для

    компилятора. Человеку, чтобы не потеряться, нужны маяки для навигации. • Маяки можно расставлять разными способами: самим кодом, комментариями, в коммитах, в документации.
  19. Как понять, что фрагмент кода, если к нему вернуться через

    год, будет непонятен новому разработчику в команде? Куда ставить маяки?
  20. Как понять, что фрагмент кода, если к нему вернуться через

    год, будет непонятен новому разработчику в команде? Вообще это с опытом приходит :(. Но на первое время есть простые заклинания. Куда ставить маяки?
  21. Куда ставить маяки? Для фрагмента кода представляем себя на месте

    нового разработчика и задаем вопрос: зачем?
  22. Куда ставить маяки? Для фрагмента кода представляем себя на месте

    нового разработчика и задаем вопрос: зачем? Потому что на вопросы “что?” и “как?” отвечает сам код, который уже есть.
  23. Примеры Классика: # Присвоим четвертую роль. user.role = 4 Бесполезно,

    дублирует уже имеющуюся в коде информацию. Не отвечает на вопрос “зачем?”. # Первый пользователь по умолчанию админ. user.role = 4
  24. Примеры Классика: # Присвоим четвертую роль. user.role = 4 Бесполезно,

    дублирует уже имеющуюся в коде информацию. Не отвечает на вопрос “зачем?”. # Первый пользователь по умолчанию админ. user.role = 4 Отвечает на вопрос “зачем”. Но можно еще лучше: # Первый пользователь. user.role = USER_ROLE_ADMIN
  25. Практика: комментарии Как обычно пишут комментарии: Удаляем пользователя Сортируем список

    Волшебные 8 байт А что было бы полезно: Коммит больше не связан с пользователем Нам нужны самые старые пользователи RFC12345
  26. Комментарии в коммитах Занимают почетное промежуточное место между комментариями в

    коде и в документации. Очень удобно отвечают на вопрос “зачем” для совокупности изменений кода.
  27. Комментарии в коммитах Упоминая в коммитах тикеты с помощью тегов

    (например, #ref и #fix), мы можем вынести часть информации в тикеты.
  28. Практика: коммиты Как обычно пишут комментарии: Удалили файл Небольшой рефакторинг

    Поменял пару строк Багфикс А что было бы полезно: Добавлен по ошибке, не нужен. Сделал имена контейнеров понятнее #ref 1963: пытаемся понять, почему падает #fix 1963
  29. Пошаговая инструкция: 1. Если код сам отвечает на вопрос “зачем”

    - ничего не делаем. 2. Если можно добавить информацию в сам код и он не лопнет - добавляем. 3. Если можно добавить информацию в документацию так, чтобы она не лопнула и не потеряла связь с действительностью через месяц, - добавляем. 4. Если ничего из вышеописанного не получается - пишем комментарий, отвечающий на вопрос “зачем?”. Пишем только то, чего нет в самом коде. Логически завершенные части кода коммитим, снабжая коммит комментарием, отвечающим на вопрос “зачем?”.
  30. Документирование API Отдельная история. Это информация для внешних и внутренних

    разработчиков, которые не видят код и не знакомы с проектом. Хорошим тоном считается документировать API полностью.
  31. Генерация документации Генераторы, такие как sphinx, позволяют создавать документацию из

    комментариев. Всегда помните: эти средства предназначены для генерации документации API, а не всего проекта.