Думаю сейчас все программисты используют системы автоматического документирования кода типа javadoc, когда к полям, методам и другим вещам можно писать комментарии в особом формате, который затем распознаётся IDE и системой документирования для создания документации. Это очень удобно, когда читаешь чужой код, наводишь мышкой на какой-то незнакомый метод и тебе в подсказке всплывает его описание, сразу становится всё ясно и не нужно лезть искать этот метод чтобы прочитать его код или доказываться по названию о его назначении, когда это может быть не очевидно. Есть и минусы. Главный минус я считаю это то что код, после снабжения такими комментариями для системы документирования, становится сложно читать, потому что комментариев там больше чем самого кода. Загляните в какой-нибудь файлик стандартной ява библиотеки. Брр. И второй минус, это то что для создания красивой документации приходится использовать всякие специфические конструкции в комментариях и даже html-теги, после чего сам по себе комментарий прочитать становится сложно, зато в выводе системы документирования или при наведении мышкой на переменной комментарий будет красивый.

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

Ну и вообще кто что думает насчет минусов и плюсов про которые я писал Дискасс в общем.