Написание хороших комментариев

Это часть краткой серии статей о хороших привычках Java-программистов.

Не пересказывайте свой код

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

/** Calculates profit. */
public class ProfitCalculator {
    private double buyerPrice; // the buyer's price
    private double sellerCost; // the seller's cost

    // default constructor
    public ProfitCalculator() {
        // assign buyerPrice
        this.buyerPrice = 0.0;

        // assign sellerCost
        this.sellerCost = 0.0;
    }

    public ProfitCalculator(double buyerPrice, double sellerCost) {
        // Save the buyer price in a member field.
        this.buyerPrice = buyerPrice;

        // Save the seller cost in a member field.
        this.sellerCost = sellerCost;
    }

    // Sets the buyer price.
    public void setBuyerPrice(double buyerPrice) {
        this.buyerPrice = buyerPrice;
    }

    // More code would follow.
}
Войти в полноэкранный режим Выход из полноэкранного режима

Ни один из этих комментариев не добавляет ничего полезного.

Поскольку автор использовал осмысленные имена для переменных и методов, комментарий здесь

ничего не добавляет и не нужен.

Метод с сигнатурой

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

Давайте посмотрим на это:

    // Default constructor
    public ProfitCalculator() {
Войти в полноэкранный режим Выйти из полноэкранного режима

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

Это приводит к несколько сложной ситуации для студентов. Возможно, вы считаете, что все еще полезно добавить в конструктор по умолчанию //конструктор по умолчанию, потому что это полезно для вас, когда вы только начинаете. Здесь я разрываюсь: Мне нравится, что вы добавляете комментарии, которые, по вашему мнению, действительно полезны и действительно полезны для вас. Но мы можем предположить, что читатели нашего кода знают основы Java, и поэтому им не нужны конструкторы по умолчанию и другие стандартные части Java, если только по какой-то причине без вашего комментария не будет сложно увидеть эти вещи.

Другой пример

    // default constructor
    public ProfitCalculator() {
        // assign buyerPrice
        this.buyerPrice = 0.0;

        // assign sellerCost
        this.sellerCost = 0.0;
    }
Вход в полноэкранный режим Выход из полноэкранного режима

Любой человек, знакомый с Java, знает, что эти строки в теле конструктора — это операторы присваивания и то, каким переменным они присваиваются. Поэтому добавлять такие комментарии бесполезно.

Так какие же комментарии следует включить?

Здесь я буду довольно еретичен. Если вы использовали осмысленные имена для своих классов, переменных, методов, параметров и так далее, то их может быть очень мало! В идеале код является самодокументирующимся, поскольку из названий вещей и потока ваших утверждений очевидно, что программа делает и почему. Особенно для размера программ, которые вы пишете.

Менее еретично то, что каждый раз, когда ваша программа делает что-то важное, на что читатель может не сразу обратить внимание, это заслуживает комментария. Что не так с комментариями в предыдущем разделе, так это то, что они слишком много внимания уделяют тому, что делает код, а не тому, почему он это делает. Для свободно читающих на Java «что» часто не является проблемой. Именно тогда, когда они не понимают, почему ваш код делает то, что он делает, им может понадобиться помощь.

Поэтому, если вы, например, по какой-то причине пропускаете строку ввода из файла или элемент массива, вам следует это прокомментировать:

        // We need to skip printing the first price because
        // it has already been printed in <some other place>, 
        // so we start iterating at 1.
        for (int i = 1; i < prices.length; ++i) {
            System.out.println(prices[i]);
        }
Войти в полноэкранный режим Выйти из полноэкранного режима

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

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

Грамматика

Комментарии должны быть грамматическими

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

Комментарии не должны содержать сокращений

Это немного «горячая» точка зрения, но не сокращайте текст там, где уточнение было бы более понятным, за исключением случаев, когда используются очень стандартные сокращенные термины, такие как e.g. и etc.. Поэтому вместо того, чтобы сказать

скажите

Комментарии должны быть полными предложениями, заканчивающимися точками.

Это абсолютно верное решение, и, безусловно, большинство разработчиков так не делают. Я научился настаивать на этом у своего коллеги, и мне это нравится. Опять же, комментарии должны быть полезными. Полные предложения обычно более полезны, чем неполные. А решение писать полные предложения (и убирать сокращения) снимает для вас вопрос о том, насколько нестандартным может быть ваш английский. Просто пишите полное, грамматически правильное предложение с полными словами, и вы, и ваши читатели кода будут благодарны вам при чтении, и вам не придется обсуждать в голове, понятен ли ваш фрагмент предложения с аббревиатурами. Это облегчит программирование, и вы сможете писать свои комментарии хорошо и последовательно, потому что теперь у вас есть простое правило.

Оцените статью
devanswers.ru
Добавить комментарий