Как стать автором
Обновить

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

Время на прочтение 2 мин
Количество просмотров 10K
Не важно на каком языке мы пишем программу, ее необходимо комментировать.
Очень часто комментарии не выполняют свою задачу, а просто создают объем и то, что написано приходится разбирать без подсказок, иногда обращаясь к дополнительным файлам программы, что сказывается на скорости разработки.

Сам топик решил написать после того, как мне пришлось усовершенствовать несколько своих старых программ. В частности столкнулся с тем, что когда их писал не дал должного внимания написанию комментариев и в результате прошло 4 года и я наступил на свои грабли, потратив лишнее время на разбор своего старого кода. Поэтому и родился этот топик, дабы акцентироваться на важности комментариев в коде. Были сделаны выводы, которыми делюсь ниже.

Хорошие комментарии позволяют работать только с конкретным куском кода и не искать ответы в других местах, они отвечают на те вопросы, ответ на который мы не можем найти в данном месте.

Решил напомнить несколько советов, которых нужно придерживаться при написании комментариев к коду.

Несколько советов

0. Приоритетная задача каждого программиста — это актуальные комментарии.
1. «Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живете» — Макконнелл, Стив.
2. Комментируем код именно для себя (грамотно, чтоб и другие поняли).
3. Не нужно комментировать очевидные вещи.
4. Комментарий должен дополнять код, а не перефразировать его.
5. Если код использует стандартные функции, конструкции или классы описанные в азах языка, то не тратьте свое время, в данном случае поможет только правильно оформленный код.
6. Комментарий к фрагменту кода, нужно писать с тем же отступом, что и у комментируемого кода.
7. Вредная привычка многих — разговаривать с кем-то в комментарии, комментарий должен быть коротким и четким.
8. В комментарии можно оставить задачу на потом, которую по каким-то причинам не выполнили в настоящий момент. Такие заметки хранить в отдельном файле не советую, потому как, кроме Вас над кодом может работать еще кто-то и проще, если он будет на месте видеть, где и что не доделано, но будет реализовано. Возможно будут найдены более актуальные решения.
9. Хорошая практика — в начале файла кратко описать его назначение.
10. Новые классы и функции — желательно описать, какие и от куда попадают входящие данные и какая цель.
11. Дабы избавится от лишних комментариев кода, можно выбирать название классов, функций, объектов и т.п. по назначению.

Вывод

В результате мы и наши коллеги не будем тратить лишнее время на комментирование. Мы не будем раздражать людей, которые возьмутся разбирать код, а даже порадуем их в какой-то момент.

Так же для любителей объёмных комментариев могу посоветовать заменить их на отдельную документацию.

Экономьте свое время и пощадите тех кто будет работать над вашим кодом.

P.S. Поздравляю всех с прошедшим праздником программиста, желаю, чтоб ваши интересы и ваша работа — были одним целым. Чтоб клиенты были отличные и любое начатое дело доводилось до успеха.
Теги:
Хабы:
+5
Комментарии 13
Комментарии Комментарии 13

Публикации

Истории

Ближайшие события

Московский туристический хакатон
Дата 23 марта – 7 апреля
Место
Москва Онлайн
Геймтон «DatsEdenSpace» от DatsTeam
Дата 5 – 6 апреля
Время 17:00 – 20:00
Место
Онлайн