Как не нужно писать документацию

    Вот что сегодня встретилось в javadoc'е к фреймворку Smart GWT.

    image

    А ведь между прочим, еще продается и коммерческое издание.
    Поделиться публикацией

    Комментарии 10

      0
      Такие комментарии пишут, когда нечего сказать о коде. Разработчик, находясь в контексте, считает комментирование таких тривиальных участков кода лишним, но комментарий нужен и он есть. Решается это либо воспитанием самодисциплины, либо рецензированием кода. «Описывайте „почему“, а не „как“ (с) П. Гудлиф.
        +4
        Я так понимаю, подобные комментарии автоматически генеряться.
          +1
          (смотрит на тэги) вставлять скрипту руки? ну-ну :)
            0
            Не скрипту — разработчику!
            +1
            А что вы хотели от описания гэттэра и сэттера? Описание назначения переменной явно где то в другом месте. И скорее всего, разработчику нужно было написать комментарий к обеим функциям.
              0
              В том-то и дело, что нет его нигде. Часть тех же геттеров/сеттеров у них сделана хорошо — с описанием, что за поле берем/устанавливаем и что оно означает.
                +2
                Я встречал такую ситуацию в одном коде. В нем разработчик дал ёмкое описание поля в приватной части класса, а для публичных get/set методов дал пространное описание «возвращает/устанавливает переменную...».
              0
              Я с подобной штукой каждый день работаю(всего два дока, один из которых AVM2 overview). Печально но лучше чем ничего.
                +1
                Действительно ужасно. Даже тот-же GhostDoc пишет более осмысленные комментарии.
                  0
                  Примерно такие комментарии для get/set по умолчанию генерирует eclipse.

                  А что тут можно сделать?
                  Дублировать описание поля в комментарии для геттера и в сеттера?

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

                  Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                  Самое читаемое