Javadoc как пользоваться idea

Практическое занятие «Генерация Javadoc из примера проекта»

Javadoc является стандартным выводом для API Java. Создание Javadoc довольно простое. Javadoc генерируется с помощью так называемого «доклета». Различные доклеты могут по-разному анализировать аннотации Java и создавать разные выходные данные. Но по большому счету почти каждая документация по Java использует стандартный доклет. Выходные данные Javadoc знакомы разработчикам Java и приветствуются ими.

Javadoc поддерживается Oracle. Разработчики могут интегрировать вывод Javadoc непосредственно в свою IDE, что делает документацию удобной и легко доступной. Фактически, Javadoc часто доставляется таким образом, а не разворачивается и загружается на сервер. Javadoc содержит только справочную документацию. В документацию нельзя добавлять какие-либо концептуальные файлы справки или изменять макет.

��‍�� Генерация Javadoc

В этом упражнении создадим Javadoc из загруженного ранее примера проекта Java. Посмотреть итоговый вывод Javadoc можно здесь.

• В Eclipse переходим в File > Export;
• Раскроем Java и выберем Javadoc. И нажмем кнопку Next;
• Выбираем свой проект и пакет. После, в правой панели классы, которые нужно включить в Javadoc: в этом примере это будут Dynamite.java и ACMESmartphone.java.

Выбирать класс App.java , который содержит метод main не нужно, потому что не нужно предоставлять документацию по Java для вашей программы. Javadoc предоставит документацию для классов, которые разработчики могут использовать в своих программах. В этом примере проекта основной метод включен в App.java, но он мог бы быть включен в файл и с другим именем.

• Выбираем вариант видимости: Private, Package, Protected, или Public. Как правило выбирают Public.

API, может иметь множество вспомогательных или служебных классов, используемых в бэкэнде, но разработчиками будет использоваться только определенное количество классов. Эти классы созданы public. Классы, которые разработчики будут использовать, формируют аспект API библиотеки классов.

• Убедимся, что радиобаттон Use standard doclet выбран (Выбирается по умолчанию).
• Нажимаем кнопку Browse и выбираем место, куда выводить сгенерированный Javadoc. По умолчанию он будет генерироваться в подпапке doc , созданной в той же папке, где хранится код. Таким образом, просматривать Javadoc можно непосредственно в Eclipse IDE.

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

Tip: Когда разработчики предоставляют библиотеки Java, они часто добавляют документацию непосредственно в JAR-файл. Пользователи привыкли искать документацию в папке doc.

• Нажимаем Next и видим окно с дополнительными настройками конфигураций.

Здесь вы можете выбрать пропуски тегов, такие как @author и @deprecated. Как правило, исключается тег @author, поскольку он может быть важен только внутри, а не снаружи. Можно выбрать различные параметры во фрейме Javadoc. Если есть кастомизированная таблица стилей, то указать ее можно здесь. Скорее всего, изменения стиля будут только поверхностными, например, с цветами.

• Нажимаем Next

Здесь можно выбрать HTML-страницу, которая будет обзорной страницей в Javadoc. Можно выбрать любую HTML-страницу, и она будет включена в индекс.

Если кнопка Finish неактивна, это может быть связано с тем, что Eclipse не может найти нужный исполняемый файл Javadoc. Можно нажать Configure и найти файл вручную. На MacBook Pro файл Javadoc находится по адресу /Library/Java/JavaVirtualMachines/jdk1.8.0_171.jdk/Contents/Home/bin/javadoc .

Если будет предложено обновить местоположение Javadoc (которое, вероятно, отличается от местоположения рабочего пространства Eclipse), стоит это сделать, нажав Yes to all.

Перейдите к месту назначения и откройте файл index.html в браузере, чтобы просмотреть файлы.

Tip: Если возникли проблемы со сборкой Javadoc, получившуюся документацию можно посмотреть здесь.

Javadoc и проверка ошибок

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

��‍�� Изучение параметров Javadoc

Можно попробовать удалять некоторые параметры из метода и снова генерировать Javadoc. Перед этим нужно убедиться, что окно консоли открыто, чтобы можно было видеть предупреждения об ошибках.

Автоматическое создание Javadoc

В большинстве проектов файл Javadoc никогда не создается вручную, как описано здесь. Javadoc позволяет строить его из командной строки, передавая ему файл конфигурации. У большинства разработчиков есть инструмент управления сборкой, где они могут настраивать выходные данные из своего кода, включая Javadoc. Если разработчики попросят собрать Javadoc, скорее всего, их система управления сборкой может быть несколько примитивной. Тем не менее, может быть полезно создать выходные данные Javadoc самостоятельно (как описано здесь), чтобы протестировать и просмотреть выходные данные, прежде чем создавать их с помощью инструмента управления сборкой.

Javadocs

Javadoc comments are usually placed above classes, methods, or fields in your source code. A Javadoc provides a description of the code element located under it and contains block tags marked with @ with specific metadata.

You can generate an API reference for your project in HTML by using the Javadoc tool that comes with your JDK. IntelliJ IDEA provides integration with the tool and allows you to build reference guides right from the IDE.

Learn more about the correct format of Javadocs, style guide, terms and conventions from How to Write Doc Comments for the Javadoc Tool.

Documentation comments are also available in JavaScript, Python, Ruby, PHP, and Kotlin.

Add Javadocs

Add a Javadoc using automatic comments

For documentation comments, IntelliJ IDEA provides completion that is enabled by default.

Type /** before a declaration and press Enter . The IDE auto-completes the doc comment for you.

You can disable automatic insertion of Javadoc comments: in the Settings dialog Control+Alt+S , go to Editor | General | Smart Keys , and clear the Insert documentation comment stub checkbox.

Add a Javadoc using context actions

• Place the caret at the declaration in the editor, press Alt+Enter , and select Add Javadoc from the list.

For method comments, the new comment stub contains the required tags ( @param tags for each method parameter, @return , or @throws ).

In Kotlin, the @param and other tags are not generated because the recommended style requires incorporating the description of parameters and return values directly into the documentation comment.

For more information about documenting Kotlin code, refer to Kotlin documentation.

Fix Javadocs

If a method signature has been changed, IntelliJ IDEA highlights the tag that doesn’t match the method signature and suggests a quick-fix.

Fix using context actions

• Place the caret at the tag, press Alt+Enter , and select an action. You can change the tag or delete it.

Fix using the Fix doc comment action

You can also update an existing Javadoc comment to account for the changes in the declaration using the Fix doc comment action :

1. Place the caret at the class, method, function, or a field, and press Control+Shift+A .
2. Type fix doc comment and press Enter .

You can use the Fix doc comment action to add missing documentation stub with the corresponding tags: place the caret within a class, method, or function and invoke the action.

Render Javadocs

IntelliJ IDEA allows you to render Javadocs in the editor. Rendered comments are easier to read, and they don’t overload your code with extra tags.

Click in the gutter next to the necessary documentation comment (or press Control+Alt+Q ) to toggle the rendered view; click to edit the comment.

Rendered Javadocs allow you to click links to go to the referenced web pages, or view quick documentation for the referenced topics.

To change the font size, right-click a Javadoc in the editor and select Adjust Font Size from the context menu. Note that the rendered comments use the same font size as the quick documentation popup.

Render Javadocs by default

You can configure the IDE to always render Javadocs in the editor.

• Right-click the ( icon in the gutter or ) and enable the Render All option. Alternatively, in the Settings dialog Control+Alt+S , select Editor | General | Appearance and enable the Render documentation comments option.

To edit rendered Javadocs, click the icon in the gutter next to the comment.

Use custom tags in Javadocs

In Javadocs comments, you can use custom tags on top the predefined ones. Later on you can include them in your API reference guide.

Recognize custom tags

When you use a custom tag for the first time, the Javadoc declaration problems inspection highlights it in the editor as a wrong tag. To avoid that, add the tag to the list recognized tags.

• Place the caret at your custom tag, press Alt+Enter , and select Add ‘@tagname’ to custom tags .
• Alternatively, press Control+Alt+S to open the IDE settings, select Editor | Inspections . Locate the Javadoc declaration problems inspection in the list and add your tag to the Additional Javadoc tags list.

Include custom tags in a Javadoc reference

To include your custom tags in an HTML Javadoc reference, add them as command-line arguments.

1. Go to Tools | Generate JavaDoc and in the Command line arguments field, specify -tag tagname:Xaoptcmf:»taghead» . Example: -tag location:a:»Development Location:» Xaoptcmf determines where in the source code the tag is allowed to be placed. You can use a to allow the tag in all places. Learn more about block tags in Javadocs from the Oracle documentation.
2. Configure other options as described in Generate a Javadoc reference and generate the reference guide. The information from the tag is displayed on the corresponding pages.

Generate a Javadoc reference

IntelliJ IDEA provides a utility that enables you to generate a Javadoc reference for your project.

1. Go to Tools | Generate JavaDoc .
2. In the dialog that opens, select a scope: a set of files or directories for which you want to generate the reference.
3. In the Output directory , specify the folder to which the generated documentation will be placed. The Output directory is a mandatory field: you cannot generate a Javadoc file as long it is empty.
4. From the Visibility level list, select the visibility level of members that will be included in the generated documentation:
   • Private : include all classes and members. The level corresponds to the -private Javadoc parameter.
   • Package : include all classes and members except the private ones. The level corresponds to the -package Javadoc parameter.
   • Protected : include only public and protected classes and members. The level corresponds to the -protected Javadoc parameter.
   • Public : include only public classes and members. The level corresponds to the -public Javadoc parameter.
5. You can specify a locale (for example en_US.UTF-8 ), command line arguments, and the maximum heap size.
6. Click Generate to generate the reference.

Specify Generate JavaDoc Scope dialog

The Tools | Generate JavaDoc dialog invokes the Javadoc utility. The controls of the dialog correspond to the options and tags of this utility.

Use this area to specify the subset of files, folders, and packages for which Javadoc should be generated.

This scope can be the whole project, recently modified files, current file, custom scope, and so on.

Include test sources

Include documentation comments for test to the generated Javadoc.

Include JDK and library sources in -sourcepath

If this checkbox is selected, then paths to the JDK and library sources will be passed to the Javadoc utility. For more information, refer to documentation.

Link to JDK documentation (use -link option)

If this checkbox is selected, the references to the classes and packages from JDK will turn into links, which corresponds to using the -link option of the Javadoc utility.

This checkbox is only enabled when a link to the online documentation is specified in the Documentation Paths tab of the SDK settings.

For more information, refer to the Javadoc documentation.

Specify the fully qualified path to the directory where the generated documentation will be stored. Type the path manually or click and select the location in the dialog. The specified value is passed to the -d parameter of the Javadoc utility. If the specified directory does not exist in your system, you will be prompted to create it.

Note that unless the output directory is specified, the OK button is disabled.

Specify the visibility level of members that you want to include in the generated documentation:

• Private : include all classes and members. The level corresponds to the -private Javadoc parameter.
• Package : include all classes and members except the private ones. The level corresponds to the -package Javadoc parameter.
• Protected : include only public and protected classes and members. The level corresponds to the -protected Javadoc parameter.
• Public : include only public classes and members. The level corresponds to the -public Javadoc parameter.

Generate hierarchy tree

Generate the class hierarchy. If this checkbox is cleared, the -notree parameter is passed to Javadoc.

Generate navigator bar

Generate the navigator bar. If this checkbox is cleared, the -nonavbar parameter is passed to Javadoc.

Generate the documentation index. If this checkbox is cleared, the -noindex parameter is passed to Javadoc.

Separate index per letter

Generate a separate index file for each letter. If this checkbox is cleared, the -splitindex parameter is passed to Javadoc.

The checkbox is available only if the Generate index checkbox is selected.

Document the use of the class and the package. When selected, the checkbox corresponds to the -use Javadoc parameter.

Include the @author paragraphs. When selected, the checkbox corresponds to the -author Javadoc parameter.

Include the @version paragraphs. When selected, the checkbox corresponds to the -version Javadoc parameter.

Include the @deprecated information. When the checkbox is cleared, the -nodeprecated parameter is passed to Javadoc.

Generate the deprecated list. When the checkbox is cleared, the -nodeprecatedlist parameter is passed to Javadoc.

The checkbox is available only if the @deprecated checkbox is selected.

Type the desired locale.

Command line arguments

Type additional arguments to be passed to a Javadoc. Use the command line syntax.

Maximum heap size

Type the maximum heap size in Mb to be used by Java VM for running Javadoc.

Open generated documentation in browser

Automatically open the generated Javadoc in a browser.

Troubleshoot

javadoc: error – Malformed locale name: en_US.UTF-8

Clear the Locale field. In the Other command line arguments field, add -encoding utf8 -docencoding utf8 -charset utf8 .

-encoding specifies the encoding of the source files. -docencoding specifies the encoding of the output HTML files and -charset is the charset specified in the HTML head section of the output files.

Reference: Javadoc code style

You can configure code style for your Javadocs. Press Control+Alt+S to open the IDE settings and then select Editor | Code Style | Java | Javadocs . Configure the options as necessary and use the right part of the dialog to preview the changes.

Learn how to reformat your code from Reformat code.

In this area, define the way Javadoc comments should be aligned.

• Align parameter descriptions : select this checkbox to have parameter descriptions aligned against the longest parameter name. Otherwise, the description is separated from the corresponding parameter name by a single space.
• Align thrown exception descriptions : select this checkbox to have thrown exception descriptions aligned against the longest exception name. Otherwise, the description is separated from the exception name by a single space.

In this area, define where blank lines should be inserted in Javadoc comments.

• After description : select this checkbox to have a blank line automatically inserted after the description section of a Javadoc comment.
• After parameter descriptions : select this checkbox to have a blank line inserted after the group of @param tags.
• After return tag : select this checkbox to have a blank line inserted after the @return tag.

In this area, define whether invalid tags should be preserved or not.

• Keep invalid tags : select this checkbox to have the @invalidTag preserved.
• Keep empty @param tags : select this checkbox to have @param tags without description preserved.
• Keep empty @return tags : select this checkbox to have @return tags without description preserved.
• Keep empty @throws tags : select this checkbox to have @throws tags without description preserved.

In this area, specify additional formatting options for Javadoc comments.

• Enable leading asterisks : start each line of a Javadoc comment with an asterisk.
• Use @throws rather than @exception : use the @throws tag.
• Wrap at right margin : wrap the text that exceeds the right margin to the next line.
• Generate «

  » on empty lines : automatically insert the

  tag on an empty line.

• Keep empty lines : select this checkbox to have manually added empty lines preserved.
• Do not wrap one line comments : keep short comments on one line with the opening and closing tags.
• Preserve line feeds : if this checkbox is not selected (by default), line feeds are not preserved on reformatting. This is convenient when comments should be formatted within the boundaries of a paragraph, to occupy minimum space. If this checkbox is selected, line feeds will be preserved.
• Parameter descriptions on new line : place the description of a Javadoc parameter (if any) to a new line. It uses the indent based on the continuation indent value.
• Indent continuation lines : indent subsequent lines in multiline comments.

Productivity tips

View Javadocs in the editor

In IntelliJ IDEA, you can view external Javadocs for any symbol or method signature right from the editor. To be able to do that, configure library documentation paths or add downloaded documentation to the IDE.

• Hover over the necessary symbol in the editor.
• Place the caret at the symbol and press Control+Q ( View | Quick Documentation ). Press Control+Q again to open this documentation in the Documentation tool window.

Life in action.

При написании кода, разработчики, обычно уделяют мало внимания его документированию. Тем не менее javadoc-документация нередко может являться единственным источником информации о методах, классах, да и о приложении в целом. Поскольку javadoc является частью исходного кода, вся ответственность за ее написание ложится на плечи разработчика.

Современные среды разработки позволяют, отчасти, облегчить труд разработчику, и предлагают средства для генерирования javadoc-комментариев.

В среде разработки IntelliJ IDEA, при создании нового класса, автоматически добавляются стандартные комментарии, содержащие информацию об имени автора, дате и времени создания класса. Для полей и методов комментарии приходится писать самостоятельно.

К счастью, для IDEA есть полезный плагин JavaDoc Sync Plugin 8, который позволяет генерировать javadoc‘и для полей, методов и классов.

Стоит сказать несколько слов о возможностях плагина.

JavaDoc Sync Plugin позволяет синхронизировать javadoc‘и между определениями интерфейса и его реализацией, между методами суперкласса и переопределениями методов в подклассе. Когда javadoc‘и методов в подклассе отличаются от тех, что определены в суперклассе, плагин подсвечивает методы подкласса.

JavaDoc Sync Plugin генерирует javadoc по шаблону, который можно изменять.
Если в классе отсутствует javadoc хотя бы для одного метода, плагин подсвечивает определение класса. Также подсвечиваются поля и методы для которых не определены javadoc.

• зайти в настройки IDEA (File -> Settings);
• перейти на страницу Plugins;
• выбрать в списке доступных плагинов (вкладка Available) JavaDoc Sync Plugin 8;
• нажать на кнопку Download And install.

Note: В правой части страницы Plugins можно посмотреть описание каждого выбранного из списка плагина.

После проделанных действий IDEA предлагает перезапустить ее, что мы и делаем.

После перезапуска, нам нужно активировать наш плагин.

Для этого следует зайти в настройках среды разработки на страницу Inspections и поставить галочку напротив JavaDoc issues.

Теперь можно пользоваться плагином.

Для того, чтобы сгенерировать комментарий, например для класса, ставим курсор на его имя, нажимаем клавиши Alt + Enter (в Mac OS X клавиши Option + Enter) и в появившемся контекстном меню, выбираем Generate JavaDoc based on class.

Для методов и полей поступаем аналогичным образом.

Для случаев, когда мы хотим сгенерировать комментарий к методу подкласса или методу класса, реализующего интерфейс, плагин позволяет нам указать в javadoc-комментарии ссылку на javadoc метода суперкласса или интерфейса.

Для изменения шаблона генерирования javadoc необходимо зайти в настройки IDEA на страницу JavaDoc Sync Settings и отредактировать шаблон нужным образом.

Надеюсь, этот пост был Вам полезен, а плагин JavaDoc Sync Plugin 8 поможет Вам в написании комментариев и сэкономит Ваше драгоценное время =)

IntelliJ IDEA: стиль и форматирование кода

Современные инструменты позволяют упростить процесс разработки. В том числе, легче следить за стилем своего кода, стараясь сводить к минимуму его «самовольное» форматирование. В данном обзоре предлагаю ознакомиться с тем, какие средства предоставляет IDE IntelliJ Idea разработчику для того, чтобы код было приятно читать и легко понимать.

Вступление

Язык программирования очень похож на язык, на котором говорят люди. Разница лишь в том, что это особенный язык, который изначально служит для общения с компьютером, чтобы объяснить ему, что мы от него хотим. Но общения один на один с компьютером не может быть. Даже когда вы начинали изучать язык программирования, вы смотрели в книгу или на какой-то образовательный ресурс вроде JavaRush. И в этом источнике вы видели код, который поймёт компьютер. Но и вы должны понимать его по мере того, как у вас появляется знание языка Java. Как и в любом языке, в программировании приняты некоторые правила формирования кода. Например, пИсАтЬ зАбОрОм в приличном обществе посчитается правилом дурного тона, а в Java называть метод с большой буквы является грубым нарушением code style. Правила оформления Java кода сформулированы в документе Java Code Convention. Кроме того, стиль оформления кода может регламентировать и более мелкие детали, например, отступы. А когда используются средства контроля версий, представьте себе весь кошмар, когда каждый будет сохранять файл то с отступами в виде tab, то с отступами в виде пробелов. Каково будет тому, кому надо проверить правку всего в одном методе, а изменён будет весь файл из-за исправления пробелов на табы или наоборот. Естественно, как и с обычным языком, стиль может меняться в зависимости от того места, где он используется. Например, на просторах сети можно найти Google Java Style Guide или Twitter Java Style Guide. Для этой обзорной статьи нам понадобится испытуемый. Воспользуемся услугой системы сборки проектов Gradle. Он позволит нам создать по шаблону новый проект для быстрого старта. У Gradle есть замечательный плагин: Build Init Plugin. Перейдём в новый каталог и выполним там команду: gradle init —type java-application После этого запускаем IntelliJ Idea. Если у вас появится окно с уже открытым проектом (увидите редактор кода, дерево структуры проекта), закроем этот проект при помощи File —< Close Project . Теперь в окне приветствия выполним "Import Project" и импортируем наш новый проект. При импорте выставим флаг "Use autoimport" . Давайте разбираться, можно ли как-то упростить жизнь при помощи современных инструментов разработки.

Форматирование кода в Idea

Выполнив импорт проекта, нажмём комбинацию клавиш Ctrl+N и перейдём в класс AppTest . Этот класс — класс теста по умолчанию. Он имеет следующий вид:

 import org.junit.Test; import static org.junit.Assert.*; public class AppTest < @Test public void testAppHasAGreeting() < App classUnderTest = new App(); assertNotNull("app should have a greeting", classUnderTest.getGreeting()); >> 

Что тут сразу бросается в глаза? Аннотация с объявлением метода на одной строке, что выглядит некрасиво, согласитесь. Как же это исправить? В IntelliJ Idea есть раздел меню «Code» для различных манипуляций с кодом. Одной из такой манипуляций является «Reformat Code» или комбинация клавиш Ctrl + L . После применения аннотация будет на одной строке, а сам метод — на другой. Стоит сразу заметить, что данная операция выполняется над выделенным участком кода. А если такого нет, операция форматирования будет выполнена над всем содержимым. Давайте теперь добавим новый тестовый метод:

 @Test public void testSummOfOddNumbers() < Listdata = Arrays.asList(1, 4, 2, 3, 6, 7, 9); Integer result = data.stream().filter(number -> number % 2 == 0).reduce((n1, n2) -> n1 + n2).get(); assertThat(result, is(12)); > 

И два импорта:

 import static org.hamcrest.CoreMatchers.is; import static org.junit.Assert.assertThat; 

Как видно, операция над Stream размещена в одну строку. А что если мы хотим сделать так, чтобы всегда методы, вызов которых выстроен в цепочку, разбивало по точке на новые строки? С одной стороны, мы можем это сделать вручную. Но помните, что мы хотим, чтобы у нас всё работало само. Ведь периодически мы будем забывать, и формат кода станет везде разным, а это не есть хорошо. Получается, надо отредактировать правило, по которому Idea выполняет форматирование. Выберем в Idea в меню пункт File -> Settings (или нажмём Ctrl + Alt + S ). В поле поиска в окне настроек напишем «Code style». В разделе Code style есть возможность указать настройки не только для Java. Но сейчас нас интересует именно Java. Как видно, настройки разбиты на несколько вкладок. Что самое полезное, так это то, что результат изменения будет показан на примере в правой части окна:

Как видно на скриншоте, мы можем указать настройку для «Chained method calls» как «wrap always», т.е. разбивать всегда для объединённых вызовов методов. Теперь нажмём ещё раз форматирование в тесте и увидим, что это действительно работает! Но иногда бывает, что есть нужда отформатировать какой-нибудь код вне общих правил форматирования. Настроим форматирование следующим образом:

Чтобы форматирование можно было отключать, в разделе Code Style необходимо включить поддержку маркеров отключения форматирования:

Теперь мы сможем изменить код нашего теста так, что его форматирование останется в том виде, в котором это напишем мы:

 @Test public void testSummOfOddNumbers() < Listdata = Arrays.asList(1, 4, 2, 3, 6, 7, 9); // @formatter:off Integer result = data.stream().filter(number -> number % 2 == 0) .reduce((n1, n2) -> n1 + n2) .get(); assertThat(result, is(12)); // @formatter:on > 

Да, если вы заметили: когда вы нажимаете Tab, Idea за вас его интерпретирует как пробелы (поведение по умолчанию). Но изменить это можно там же в Code Style:

Как Вы видете, там огромное множество настроек. Более подробно про настройки Code style можно прочитать здесь: «Idea Help: Code Style». Есть ещё одна важная особенность форматирования — форматирование импортов. Оно выполняется отдельно и называется «Optimize Imports» и находится в пункте меню Code -> Optimize Imports (Ctrl + Alt + O). Оптимизация импортов убирает ненужные импорты, а также располагает их в правильном порядке в соответствии с настройками из вкладки Imports настроек Code Style для Java. Кроме того, если вам захочется, чтобы форматирование происходило автоматически, для вас есть хорошая новость: это можно сделать при помощи плагина Save Actions.

Распространение настроек в команде

Отлично, выше мы увидели, что можно настроить стиль форматирования так, как нам удобно. Но как этот стиль использовать в команде? Очень просто. Есть несколько вариантов. Самый простой — сохранить схему. Откроем настройки Idea через File -> Settings (или нажмём Ctrl + Alt + S). В разделе Code Style мы можем увидеть надпись Scheme. Это наша схема форматирования. По умолчанию указана схема с именем Default и рядом приписка IDE: это значит, что это настройка только для нашей IDE, и она не действует ни на кого. Чтобы сделать «пользовательскую» схему, по кнопке справа делаем «дубликат» и даём ему название, например: JavaRush

После этого мы сможем импортировать или экспортировать настройки:

Другой вариант — это импорт импорт настроек Idea:

Третий вариант — Settings Repository. Про использование Settings Repository см. подробнее документацию «IntelliJ Idea Help : Settings Repository». В тему распространения единого стиля в команде также не могу не отметить хорошую поддержку стилей из IDE Eclipse. Для этого потребуется установка отдельного плагина: откройте настройки Idea через File -> Settings (Ctrl + Alt + S) и перейдите в раздел Plugins. Для поиска новых плагинов нажмём кнопку «Browse Repositories» , после чего в окне поиска найдём плагин Eclipse Code Formatter.

Теперь, после установки, необходимо перезапустить Idea — это стандартная процедура. После этого всё там же, в настройках Idea, мы найдём новый раздел: «Eclipse Code Formatter» Пример файла форматирования для Eclipse можно взять здесь. Выглядеть это будет примерно так:

Ужесточение требований

Помимо средств Idea, можно также использовать плагины систем сборок для ужесточения требований. Никак не проверишь, что человек использовал форматирование. Если в команде 5 человек — ещё можно. Если в компании 100 человек — нереально. Да даже за пятью уследить будет трудно. Да и зачем лишняя трата времени на такое? Куда проще запретить собирать проект при нарушении некоторых правил. На самом деле, это уже целая отдельная тема под названием «Inspect Code». В рамках данной статьи хочется просто показать, как это работает. Одним из самых распространённых плагинов для Gradle (т.к. он собирает у нас проект, если помните) является pmd. Для его включения достаточно перейти в build script нашего gradle проекта (файл build.gradle в корне нашего проекта) и указать в нём pmd рядом с остальными плагинами:

 plugins < // Apply the java plugin to add support for Java id 'java' // Check source code id 'pmd' // Apply the application plugin to add support for building an application id 'application' >

Теперь можем задать более детальные настройки там же:

Даже в нашем проекте уже всё не хорошо. Выполним gradle build и получим ошибку. Что приятно, при сборке формируется отчёт. И если будут ошибки, мы получим сообщение вида:

 BUILD FAILED in 35s 6 actionable tasks: 6 executed 7 PMD rule violations were found. See the report at: file:///C:/_study/codestyle/build/reports/pmd/main.html 

Если мы перейдём в отчёт, увидим что-то вроде:

Причём в колонке Problem дана ссылка на описание проблемы на сайте плагина pmd. Например, для ошибки «headerCommentRequirement Required» ссылка ведёт сюда: pmd — CommentRequired. Данная ошибка намекает нам, что наш класс не имеет JavaDoc. Наличие JavaDoc над классами можно настроить при помощи шаблонов:

И указать для File Header содержимое:

После этого можем превратить комментарий над классом App в JavaDoc и увидим при новом Build, что ошибка исчезла.

Итог

• Видео от JetBrainsTV: «Inspect Code (IntelliJ IDEA)»
• Обзор «Code Analysis With Gradle Plugins»
• Курс «Automate Code Quality»