Давайте писать комментарии к коду
4 июня, 2010 11 комментариев
Хотел бы немного порассуждать на тему написания комментариев к коду. С одной стороны кажется, что разработчик это такой супермозг, который должен уметь читать любой код. Есть там комментарии или нет, по фиг. Ты же «голова», разберешься. Неважно, что метод в сто тыщ миллионов строк и неважно, что давным-давно человечество придумало отступы и переносы — это всё для дрищей. Настойщий программер может прочитать хоть стопицот строк кода и понять, что собственно они делают, даже если все эти строки это одна большая такая строка. Считаю, что это полный отстой. Не зря же придумали классы, методы и поля. Всё это только для того, чтобы суметь логически разделить программный код в надежде, что это поможет разработчикам и ускорит процесс разработки. К примеру, сложный какой-то функционал, который весь и не поместится в голове дробится на несколько взаимосвязанных больших частей. Каждая часть также разделяется на несколько менее сложных частей и так далее. В конце концов мы приходим к классам с методами. А теперь, чтобы быстрее понять, что делает класс и его методы мы начинаем комментировать код. К примеру в комментарии к классу обозначить проблему, которую решает класс, не зря же мы его создавали. Для каждого метода тоже неплохо было бы написать небольшой комментарий, который не будет отпиской, что типо чото есть, а коротким комментарием, по которому человек со стороны быстро сможет понять метод, его функции и логику работы. Кроме этого я считаю, что внутренний код также нуждается в комментировании. К примеру, если код метода достаточно сложный, то его можно логически разбить на несколько частей и каждую часть прокомментировать соответствующим образом. Считаю, что такое поможет не только тем, кому посчастливится влезть в наш гавнокод красивый код, но и нам же самим, если придется через пару месяцев что-то переделывать и переписывать.
Конечно рассуждать всегда намного проще, чем использовать это на практике и не всегда хочется или получается комментить, но как говорится стремиться надо. Так вот к чему это я всё. А к тому что в Java есть такое средство, как javadoc, которые позволяют не просто комментировать код, но и потом генерировать документацию по классам и их методам с помощью специальных тулзовин. Я при разработке использую Eclipse. Как можно сгенерировать документацию к классам по джавадокам в Eclipse можно посмотреть здесь.
Java Swing и другая джава 
прочитал =) ознакомился =) про джава-док знал, пользовался когдато только при сдаче курсовой. про важноть коментов полностью согласен с автором, так как через месяц уже надо какойто время, чтобы вспомнить, что и как ты писал, а, так как я прогер постоянно, чтото меняющий (то отступы, то стиль написания переменных, методов, для естетического восприятия) вообще код каждый раз как «первый раз вижу» =). Тут вспомнил, про стиль отступов, так вот если кому интересно, в еклипсе есть такая функция — загрузка разных принятых стилей оформления кода, ну например, таб — 3 или 4 пробела, { — эти скобки ставить с новой строки или в продолженении старой, названия переменных\методов писать с большой или маленькой буквы, вообще это дело привычки, но можно брать и пользоватся общепринятыми стилями, что тоже ускорит работу с кодом. ну и еще хотелось бы добавить, что стоит учится ПРАВИЛЬНО раставлять коментарии, т.е. только по сути и там где надо, думаю вы согласитесь, что если написать
int i = 4; // это переменная
кэп будет вами гордится, а вы через время гляните и подумаете, ну я и «клоун был» =))
Да, писать тоже надо уметь. Можно буквально парой слов весь смысл передать, а можно нафигачить десять абзацев совсем не того, что надо 🙂
=) вообще на большой и сложный проект джава-док лучший вариант, там все удобно генерируеся в удобный формат (пдф, док, штмл) и потом все просто читается
шєф, а может начешь писать статьи про кодинг в общем, т.е. не только свинг, а и патерны и вообще
Попробую 🙂
А еще лучше писать комментарии на нормальном языке типа английского, а не на своем родном — а то от таких комментариев в итоге может оказаться пользы с гулькин хрен 🙂
Ну иногда весь свой гениальный замысел автор может передать только на родном языке )
Не люблю комментарии. Я лишь между методами оставляю 10-15 пустых строк, чтобы отделить потом можно было одно от другого. А по коду я уже разберусь, что да как.
Я тоже не очень люблю излишние коментарии.. просто текстом не получается выложить то что в голове и как, выполняется то что ты сделал. а вообще периодически комментировать полезно ). кстати если бы можно было оставить графический комент там в квадратиках со стрелочками или в какой тривиальной флэш анимаци вот это было бы …
«К примеру, если код метода достаточно сложный, то его можно логически разбить на несколько частей и каждую часть прокомментировать соответствующим образом.» Может стоить тогда разбить на методы, а то какой-то говнокод? (Мартин Фаулер «Чистый код»).
Согласен, лишний раз писать комментарии на каждый чих накладно, плюс потом необходимо держать их в актуальном состоянии при модификации кода — отстой. Лучше попытаться написать методы с говорящим названием небольшого размера, чтобы моск воспринимал это частями, а не как партянку одну большую и не охеревал от этого зрелища. Но иногда бывают случаи — какая-то замудреная логика, которую вродь как и не разобьешь на части или это какие-то хитрые фиксы (особенно когда фиксы в продакшене делаются). Тогда Без комментариев не обойтись. Понятно, что вставлять туда подробное описалово из технического задания не надо, ну хотя бы линку на задачу или багу в системе багтрекинга.