4

На C++ привык оформлять классы следующим образом

(в заголовочном файле)

class MyClass
{
public:
    MyClass();
    void Method1();
    void Method2();
private:
    ...
}

Саму реализацию при этом выношу в .cpp или (в случае с header-only библиотеками) объявляю как inline и выношу ниже по тексту, отделив комментарием типа:

/*****************************/
/* Реализация класса MyClass */
/*****************************/

Это позволяет человеку, читающему мой код, быстро изучить интерфейс класса, не вдаваясь в подробности реализации.

Однако, начав изучать Java, аналогичной возможности не нашёл, и очень не хватает способа написания классов с удобно обозреваемой функциональностью. Лучшее, что посоветовали знакомые - описывать отдельно интерфейс и реализовывать его, но для классов, используемых однократно это, IMHO, overkill. Есть ли в Java способ описывать простые классы читабельно, с разнесённым объявлением и реализацией?

Update1: из комментариев стало ясно, что в Java транслятор такой возможности не предоставляет, но аналогичную функцию выполняет javadoc: либо в заголовке файла в Documentation Comments (преимущество: это первое, что видит человек, читающий код), либо после каждой сигнатуры функции (пока не понял, перед телом или после него. Преимущество: документация привязана к описанию функции). Поэтому пока непонятными остаются два момента:

  1. Как заставить IDE (Intellij IDEA) генерировать документацию для функций с подстановкой параметров, аналогично тому, как это делает Eclipse?
  2. Как заставить javadoc (или javadoc-plugin) отслеживать соответствие документации и кода чтобы, к примеру, при компиляции после изменения списка параметров функции выдалось хотя бы предупреждение?

Update2:

  1. / **перед объявлением функции работает и в IDEA.

  2. Javadoc отслеживает только комментарии, поэтому соответствие документации коду он проверить не может. Возможно, это умеют какие-либо плагины к IDE, но пока что в комментариях такой плагин не упоминался. Поэтому следить за тем, чтобы комментарии соответствовали актуальной версии кода, (и обновлялись при его изменении) приходится вручную.

  3. Обзор структуры класса частично позволяет охватить класс беглым взглядом, особенно когда IDE умеет "подсасывать" из javadoc описание функции. Возможности распечатать окошко структуры класса (как в C++ можно распечатать .h-файл для отдельного изучения) нет (точнее, я не нашёл), поэтому основной упор всё-таки надо делать на комментарии.

1
  • Если вам дан исчерпывающий ответ, отметьте его как верный (галочка напротив выбранного ответа). 8 янв 2017 в 18:46

2 ответа 2

6

В java такой возможности нет. Вы можете облегчить чтение своего кода, если будете придерживаться соглашений. Например, Java Code Convention

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

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

11
  • Посмотрел Code Convention. По сути, почти аналогичный искомому вариант - перечислять объявления методов в Documentation Comments, заодно они и в документацию попадут. Проблема только в том, что транслятор не будет отслеживать соответствие сигнатур методов в комментарии и в теле класса. Может, есть инструменты для автоматической генерации комментариев для публичных методов из кода класса?
    – BMP
    8 янв 2017 в 12:34
  • 1
    Какой транслятор вы имеете ввиду? Утилита javadoc отслеживает не соответствие, да и многие IDE отслеживают соответствие javadoc комментариев и самого кода, а так же помогают делать шаблоны для javadoc комментариев. 8 янв 2017 в 13:17
  • Речь о том, что в C++ соответствие сигнатур отслеживает транслятор - при несоответствии программа просто не соберётся. А в Java это делается внешней утилитой (видимо, javadoc), и на данный момент у меня программа собирается (в Idea) и работает вообще без Documentation Comments. Но общий смысл я понял, спасибо.
    – BMP
    9 янв 2017 в 16:10
  • Давно я с си++ не работал. Не знал, что там компилятор проверяет соответствие сигнатуры функции и документации. В java проекты обычно в ручную не собираю, а систему сборки можно настроить прогонять javadoc каждый раз после компиляции. 9 янв 2017 в 16:46
  • @BMP "соответствие сигнатур отслеживает транслятор" -- соответствие чему? Если соответствие между вызовами и объявлениями, то конечно, компилятор это отслеживает - точно так же не соберется, как и в C++. А в Java JavaDoc с точки зрения компилятора -- это просто обычный комментарий, компилятор его просто игнорирует, как и любой другой комментарий. Поддержка JavaDoc осуществляется IDE (всплывающие подсказки, лично я на практике только так их и использую), а утилита javadoc из комплекта JDK генерирует HTML-файлы с документацией, типа того, что на сайте Oracle в справке по API.
    – m. vokhm
    9 янв 2017 в 17:41
4

Сам по себе язык Java такой возможности не дает, и это, конечно, создает определенное неудобство. Однако современные IDE практически сводят это неудобство на нет. Вот как выглядит, например, фрагмент кода при работе в Eclipse:

введите сюда описание изображения

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

Заготовка для комментария (JavaDoc) со списком параметров формируется автоматически при вводе начальных символов (/**).

Кроме того, в левой панели (Package explorer) показана структура класса -- ее можно настроить, чтобы там были показаны, например, только публичные методы.

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

5
  • В Idea, как я понял, аналогичный вид получается в режиме View->Tool Window->Structure. Но пока не нашёл, как заставить javadoc в Idea формировать заголовок для комментария со списком параметров и как заставить javadoc ругаться при несоответствии параметров, описанных в документации, и фактических параметров. Это возможно?
    – BMP
    9 янв 2017 в 16:23
  • 1
    @BMP Насчет Idea - не знаю, не работал с ней. Попробуйте как в eclipse - встать в начале строки перед объявлением метода и бытро быстро набрать /** и Enter. В Eclipse при изменении параметров вручную Javadoc автоматически не корректируется и не ругается, но если использовать рефакторинг, то Javadoc корректируется - для добавленных параметров добавляет * @param newParam TODO
    – m. vokhm
    9 янв 2017 в 17:26
  • 1
    В idea просто жмите ctrl+f12, чтобы обозреть структуру классов во всплывающем окне.
    – Nofate
    10 янв 2017 в 17:47
  • @Nofate, речь о том, как делать заготовки JavaDoc и можно ли обеспечить синхронизацию между сигнатурой и JavaDoc (автоматом менять Javadoc при ручном изменении сигнатуры, напр. списка параметров)
    – m. vokhm
    10 янв 2017 в 19:44
  • 1
    @BMP Javadoc не проверяет соответствие комментариев коду. Она код вообще не разбирает, только разбирает комментарии и генерирует HTML. Насчет идеи не знаю, а в эклипсе только рефаторинг использовать. Но это нестрашно, рефакторинг все равно удобней, чем вручную менять сигнатуру у объявления а потом так же вручную у всех вызовов.
    – m. vokhm
    10 янв 2017 в 19:50

Ваш ответ

By clicking “Отправить ответ”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Всё ещё ищете ответ? Посмотрите другие вопросы с метками или задайте свой вопрос.