Меню сайта

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

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

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

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

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

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

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

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

Вывод

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

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

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

Категория: Программирование | Дата: 13.05.13

Меню раздела
Блок