TП: Руководство по стилю программирования на языке Java

Руководство по стилю программирования на языке Java

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

Кстати говоря, некоторые аспекты стиля программирования вызваны исключительно эстетическими соображениями, и не оказывают большого влияния на корректность программы. Однако эти рекомендации, упрощают эксплуатацию вашей программы, потому что весь код выглядит одинаково. Любому разработчику это сильно облегчает работу с кодом. Это как форматирование текстового документа: если во всем документе используются одни и те же правила форматирования, читать его гораздо легче, чем, если бы, каждая его часть имела бы свой собственный формат!

Люди обычно подбирают себе "любимый" стиль программирования. (Точно так же как мы выбираем любимый текстовый редактор, потовый клиент, и т.д.) Это здорово, если у вас есть привилегия самому контролировать стандарты кодирования, но во многих случаях эти стандарты вам уже заданы. Тогда, важно проявить гибкость.

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

Стиль программирования на языке Java использующийся в этом курсе

Ниже представлены рекомендации по стилю программирования:

Отступы

Каждый уровень отступов должен содержать четыре пробела. Например:

    /**
     * Этот класс хранит значения для дальнейшей работы.
     **/
    class MyClass {
        /** Важное значение. **/
        private int value;

        /**
         * Создает объект, используя указанное значение.
         **/
        public MyClass(int v) {
            value = v;
        }
    }

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

Комментарии

Каждый класс, интерфейс, метод, и поле класса должны иметь комментарий в стиле Javadoc. Такие комментарии это очень важный элемент проектирования. Комментарий не обязательно должен включать все тэги Javadoc, или быть чрезмерно подробным; он должен только описывать назначение объекта, и какие либо важные детали на которые следует обратить внимание. Например:

    /**
     * Этот класс хранит значения для дальнейшей работы.
     **/
    class MyClass {
        /** Важное значение. **/
        private int value;

        /**
         * Создает объект, используя указанное значение.
         **/
        public MyClass(int v) {
            value = v;

        }
    }

Назначение имен

Имена классов Java должны соответствовать соглашению UpperCamelCase. (В именах, составленных из нескольких слов, каждое слово начинается с заглавной буквы)
Имена методов, полей и локальных переменных Java должны соответствовать соглашению camelCase (В именах, составленных из нескольких слов, первое слово, начинается со строчной буквы, а остальные с заглавной).
Константы Java (static и final) должны соответствовать соглашению ALL_CAPS. (Все буквы в имени заглавные. Часто слова разделяют нижним подчеркиванием.)

Вот класс, иллюстрирующий правила назначения имен:

    /** Имя класса UpperCamelCase. **/
    public class WebServer {

        /**
         * Имя константы по соглашению ALL_CAPS.
         **/
        public static final int DEFAULT_PORT = 80;

        /** версия HTTP, тоже константа. **/
        public static final String HTTP_VERSION = "HTTP/1.1";

        /**
         * Тип поля UpperCamelCase, так как имена всех стандартных классы Java
         * классов Java следует этому соглашению.
         * Имя поля camelCase.
         **/
        private ServerSocket sock;
 
        /**
         * Имя конструктора такое же как у класса.  Имена аргументов
         * назначены по соглашению camelCase.
         **/
        public WebServer(String hostName, int port) {
            ...
        }

        /** Имя метода по соглашению camelCase. **/
        public HTTPRequest acceptRequest() {
            ...
        }
 
        ...
    }

Пустые строки

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

Всегда вставляйте одну или две пустых строки между объявлениями полей.
Всегда вставляйте две пустых строки между объявлением метода и тем, что следует за ним.
В теле метода, разделяйте "вычислительные блоки" или подзадачи пустой строкой. В коротких методах не должно быть пустых строк, но если тело метода длиннее 6-8 строк, подумайте где нужно вставить пустые сроки чтобы код метода лучше читался.

Пробелы

Вставляйте пробел после ключевых слов Java, таких как for, while, if, do, и т.п. Например:

    
    for (int i = 3; i < 55; i++) {
        System.out.println("Вычисление площади " + i + " стороннего многоугольника");
        computeArea(i);
    }

Вставляйте пробел перед и после бинарных операторов, таких как +, -, &&, ||, =, и т.п.. Например:

 discriminant = b * b - 4 * a * c;

Не добавляйте пробел перед точкой с запятой. (См. выше)
Не вставляйте пробел перед запятой в списке аргументов метода. Вставьте пробел после нее. Например:

processor.addJob(jobID, jobDesc, task, dueDate);

Условные операторы, циклы и блоки

Открывающая фигурная скобка должна стоять на той же строчке что и оператор, которому принадлежит начинающийся блок. Перед скобкой надо вставить пробел.
Например:

     
    if (c.hasObject(o)) {
        System.out.println("Нашли!");
        c.remove(o);
        o.dispose();
    }

Закрывающая фигурная скобка должна быть выровнена по вертикали с оператором, который начинает блок.
(См. пример выше.)
В условных операторах и циклах, тело которых состоит только из одного оператора, необязательно использовать фигурные скобки. Конечно, можете их вставить, если вам этого действительно хочется, но это явно лишнее. Пример:

    for (int i = 0; i < 30; i++) 
        fact *= i;

В условных операторах и циклах, тело которых состоит только из одного оператора, поместите этот оператор на следующую строку. Не надо писать его на той же строке!

Плохо:

    if (n > 0) r = Math.sqrt(n);

Хорошо:

    if (n > 0)
        r = Math.sqrt(n);

Проверка стиля (Checkstyle)

Checkstyle это программа проверки стиля Java с открытым кодом. Эта мощная, настраиваемая, расширяемая, а также достаточно хорошо документированная программа! Многие проекты на языке Java, в программной индустрии и в открытом доступе используют Checkstyle для проверки исходного кода на соответствие стилю программирования.

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

Установка и запуск Checkstyle

Загрузите Checkstyle и распакуйте архив. Откройте в редакторе файл sun_checks.xml, найдите и закомментируйте строку:

    <module name="DoubleCheckedLocking">>

Закомментированная строка выглядит так:

    <!--module name="DoubleCheckedLocking"/-->

Сохраните и закройте файл. Теперь для того чтобы проверить стиль вашего java файла в командной строке, надо перейти в каталог где находится дистрибутив checkstyle и ввести команду:

    java -jar checkstyle-5.6-all.jar -c sun_checks.xml -r c:\java\HelloWorldApp.java

В последнем аргументе командной строки вместо c:\java\HelloWorldApp.java надо указать путь и имя вашего проверяемого файла. Отчет вы увидите на экране. Версия checkstyle может отличаться от указанной в примере. В этом случае замените 5.6 на номер версии, которая установлена на вашем компьютере. Подробное описание работы с CheckStyle через командную строку можно посмотреть здесь: http://checkstyle.sourceforge.net/cmdline.html