Как отмечать логические участки кода в комментариях Java?

Question 1

Классы Java обычно делятся на логические «блоки». Есть ли соглашение о маркировке этих разделов? В идеале он будет поддерживаться основными IDE.

Я лично использую такой метод:

//// Section name here ////

Однако у некоторых редакторов, похоже, с этим возникают проблемы.

Например, в коде Objective-C вы можете использовать этот метод:

#pragma mark -
#pragma mark Section name here

Это приведет к появлению меню в XCode, которое выглядит следующим образом:

альтернативный текст

Question 2

Я лично использую разделители строк из 80 символов, например:

public class Client {

    //================================================================================
    // Properties
    //================================================================================

    private String name;
    private boolean checked;

    //================================================================================
    // Constructors
    //================================================================================

    public Client() {
    }

    public Client(String name, boolean checked) {
        this.name = name;
        this.checked = checked;
    }

    //================================================================================
    // Accessors
    //================================================================================

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public boolean isChecked() {
        return checked;
    }

    public void setChecked(boolean checked) {
        this.checked = checked;
    }

}

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

В Eclipse я создал набор настраиваемых шаблонов (Java -> Editor -> Templates в диалоге настроек Eclipse), которые генерируют эти полосы, например. - sepa (SEParator for Accessors) - sepp (SEParator for Properties) - sepc (SEParator for Constructors) - и т. д.

Я также изменил стандартный шаблон «нового класса» (Java -> Стиль кода -> Шаблоны кода на экране настроек Eclipse).

Также есть старый плагин Eclipse под названием Coffee-bytes , который улучшил способ сворачивания частей кода в Eclipse. Я не знаю, работает ли это до сих пор, но я вспомнил, что можно определить произвольные складные зоны, добавив специальные комментарии, например // [SECTION] или что-то в этом роде. Он может по-прежнему работать в последних версиях Eclipse, так что взгляните.

Question 3

Для студии intellij / android есть отличное решение.
Начинайте с:
//region Description
и заканчивайте:
//endregion

Ярлык для этого находится в меню, которое вы можете открыть с помощью Command+ Alt+ T(Mac) или Ctrl+ Alt+T (Windows).

Вы также можете добавить свою собственную линию для дополнительного визуального разделения, если вам это нужно. Область можно сжимать и расширять по желанию с помощью кнопок +/-, как и любую функцию. Вы также можете перемещаться между регионами с помощью Command+ Alt+ Period( Ctrl+ Alt+Period )

Источник .

Пример:

//region Parceler Implementation
//---------------------------------------------------------------------------------------
@Override
public int describeContents() {
    return 0;
}

@Override
public void writeToParcel(Parcel dest, int flags) {
    dest.writeParcelable(this.die, 0);
    dest.writeParcelable(this.dieSprite, 0);
}

private DieVm(Parcel in) {
    this.die = in.readParcelable(Die.class.getClassLoader());
    this.dieSprite = in.readParcelable(Sprite.class.getClassLoader());
}

public static final Parcelable.Creator<DieVm> CREATOR = new Parcelable.Creator<DieVm>() {
    public DieVm createFromParcel(Parcel source) {
        return new DieVm(source);
    }

    public DieVm[] newArray(int size) {
        return new DieVm[size];
    }
};
//---------------------------------------------------------------------------------------
//endregion

Question 4

Eclipse определяет аннотацию javadoc @category (прокрутите до раздела, отмеченного «Поддержка категорий»), которая позволяет фильтровать по категориям в обзоре структуры. Не совсем то, что вам нужно. Я удивлен, что никто не написал плагин Eclipse, который предлагает вид, подобный вашему снимку экрана.

Question 5

Мне это нравилось также, когда я использовал xcode. Для eclipse я использую ctrl + o (быстрое описание) для навигации по классу Java.

Question 6

Использование ненужных комментариев / маркеров в коде для облегчения работы может быть плохой практикой. Я мало знаю о разработке xcode и java, но вся основная поддержка IDE в поиске членов без каких-либо специальных маркеров, таких как eclipse, показывает методы и члены, использующие вид схемы, который можно запускать с помощью ctrl+OIntellij (который я предпочитаю использовать больше на Mac и имел Community edition тоже) имеет ту же концепцию структуры, и к ней можно быстро получить доступ с помощью (ctrl + f12). Итак, я хочу сказать, что не используйте ненужную разметку в коде, поскольку все (или, по крайней мере, хорошие / нормальные) IDE могут делать это автоматически.

Question 7

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

Лучше сгруппировать связанные члены в отдельный класс посредством наследования или агрегирования. Это считается хорошим стилем ООП

Question 8

В дополнение к предоставленному ответу Андрея, чтобы использовать // region // endregion, мы вставляем [буквы BigAscii] [1] в основные разделы кода. При быстрой прокрутке он действительно выделяется. Одним из недостатков этого подхода является то, что я не могу его найти, поэтому вам нужно будет добавить поисковый запрос чуть ниже «баннера», как я делаю ниже.

Цитата

//    _      _____          _____                  _   _
//   | |    |  __ \   /\   |  __ \      /\        | | | |
//   | |    | |  | | /  \  | |__) |    /  \  _   _| |_| |__
//   | |    | |  | |/ /\ \ |  ___/    / /\ \| | | | __| '_ \
//   | |____| |__| / ____ \| |       / ____ \ |_| | |_| | | |
//   |______|_____/_/    \_\_|      /_/    \_\__,_|\__|_| |_|
//
//   Search here with: LDAP Auth

[1]: http://patorjk.com/software/taag/#p=display&c=c%2B%2B&f=Big&t=LDAP Auth

Question 9

Я бы использовал javadoc ; или используйте в качестве простого «разделителя» следующее (одна или 3 строки):

/** RecyclerOnItemClickListener */

/** 
 * RecyclerOnItemClickListener
 */

Так что в IDE он отображается другим цветом, отличным от ненавязчивого серого с комментариями.

Question 10

Современная IDE позволяет вам просматривать ваш код по-разному и даже реорганизовывать его. Eclipse даже позволяет вам просматривать определение кода, на котором установлен курсор, на другой панели.

Любая автоматическая реорганизация вашего кода приведет к нарушению такой разметки.

Если вы хотите сгруппировать, подумайте о том, чтобы объединить вещи, принадлежащие к одному классу, а вещи, не принадлежащие друг другу, - в разные классы.

Question 11

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

Question 12

Для IntelliJ мне нравится:

        public void ________________INIT__________________() {};

выглядит красиво в файловой структуре!