Есть ли какая-то ценность в «шаблонных комментариях»?

1

В приложении, использующем Hibernate, мы имеем несколько классов сущностей, которые сопоставляются таблицам в схеме базы данных. Я видел объекты, которые кажутся бесполезными JavaDoc-комментариями и не могут не задаться вопросом, есть ли там какая-либо полезность.

Есть ли ценность для этих комментариев с мозгом? А если нет, можете ли вы сделать аргумент для его удаления?

/**
 * MyClass entity.
 */
@Entity
@Table(name="my_class")
public class MyClass {

    // Fields

    /** The id. */
    private Integer id;

    /** The name. */
    private String name;

...

    // Constructors

    /**
     * default constructor.
     */
    public MyClass() {
    }

...

    // Property accessors
    /**
     * Gets the id.
     *
     * @return the id
     */
    @Id
    @GeneratedValue(strategy = IDENTITY)
    @Column(name = "id", unique = true, nullable = false)
    public Integer getId() {
        return this.id;
    }

    /**
     * Sets the id.
     *
     * @param id
     *            the new id
     */
    public void setId(Integer id) {
        this.id = id;
    }

...

}
Теги:
hibernate
comments

2 ответа

1
Лучший ответ

Неважно.

Аргументы для удаления:

  1. Делает код более длинным, чтобы больше прокручивать. Я бы предпочел увидеть код режима на моем экране сразу, чем бесполезные комментарии, принимающие 50% экрана.

  2. Как только вы увидите, что комментарии просто пух, вы, вероятно, просто привыкнете пропускать комментарии. Даже те, которые не пух. Поэтому они фактически обесценивают любые полезные комментарии.

Поделиться
  • 0
    Ваше второе замечание отлично; Я не думал, что бесполезные комментарии вызовут (плохое) усвоенное поведение игнорирования всех комментариев.
2

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

class Foo{

    /************************
     * Variable Declaration
     */
    //Define some variables here

    /************************
     * Constructors
     */
    //Put some constructors here

    /************************
     * Methods
     */
    //Put some methods here

    /**
     * @return A description of what the variable is, not just that you are returning it
     *         so the user doesn't have to find the variable definition above and look for
     *         a description there.
     */
    void exMethod(){
        return var;
    }

}

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

Поделиться
  • 0
    Это очень хороший момент, и я поощряю это. Этот вид комментария служит организационной цели. Мой вопрос больше касается "String name; // The name". JavaDoc комментарии.
  • 0
    Да, это, как правило, немного бесполезно. Если цель / использование переменной очевидна, я не комментирую ее с описанием. И очевидно, что если описание является не чем иным, как повторением имени переменной, то я оставляю это. Я бы дал комментарий к переменной, только если она служит для добавления дополнительной информации, которую само имя переменной уже не предоставляет.
Показать ещё 2 комментария

Ещё вопросы

Сообщество Overcoder
Наверх
Меню