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