Jak oznaczyć logiczne sekcje kodu w komentarzach Java?


93

Klasy Java są ogólnie podzielone na logiczne „bloki”. Czy istnieje konwencja oznaczająca te sekcje? Idealnie byłoby, gdyby był obsługiwany przez główne IDE.

Osobiście używam tej metody:

//// Section name here ////

Jednak wydaje się, że niektórzy redaktorzy mają z tym problemy.

Na przykład w kodzie Objective-C możesz użyć tej metody:

#pragma mark -
#pragma mark Section name here

Spowoduje to wyświetlenie menu w XCode, które wygląda następująco:

tekst alternatywny


4
jako programista iOS najbardziej tęskniłem za tym, gdy zaczynałem od Android Studio
Chris Chen

1
downvoted: w przypadku nowoczesnych IDE i języków jest to kiepska praktyka. Jeśli musisz podzielić kod na sekcje, prawdopodobnie już łamiesz zasadę pojedynczej odpowiedzialności i lepiej jest podzielić go na różne klasy / pliki. Jeśli istnieje wiele edytorów, prawdopodobnie i tak po pewnym czasie będzie to niezsynchronizowane, ponieważ niektórzy będą postępować zgodnie z tym, inni będą refaktoryzować i reorganizować kod, lub automatyczne zapisywanie i formatowanie go zepsuje.
f.carlsen

downvoted: Zgadzam się z @ f.carlsen. Jeśli zorganizujesz swoją klasę za pomocą komentarzy, najprawdopodobniej złamiesz zasadę pojedynczej odpowiedzialności .
schrieveslaach

Do hejterów: zadzwoń do mnie, gdy Java obsługuje rozszerzenia klas w stylu Swift, w których możesz logicznie podzielić implementacje interfejsu na różne sekcje. I tak, klasa może dobrze implementować wiele interfejsów w tym samym czasie.
William Entriken,

Odpowiedzi:


67

Osobiście używam 80-znakowych separatorów linii, takich jak ten:

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;
    }

}

Oczywiście może się to wydawać trochę przesadzone w przypadku tak małego POJO, ale uwierz mi, okazało się to bardzo przydatne w niektórych dużych projektach, w których musiałem przeglądać duże pliki źródłowe i szybko znaleźć interesujące mnie metody. Pomaga to również zrozumieć strukturę kodu źródłowego.

W Eclipse stworzyłem zestaw niestandardowych szablonów (Java -> Edytor -> Szablony w oknie dialogowym Preferencje Eclipse), które generują te paski, np. - sepa (SEParator for Accessors) - sepp (SEParator for Properties) - sepc (SEParator for Constructors) - itd.

Zmodyfikowałem również standardowy szablon „nowej klasy” (Java -> Styl kodu -> Szablony kodu na ekranie Preferencje Eclipse)

Istnieje również stara wtyczka Eclipse o nazwie Coffee-bytes , która poprawiła sposób, w jaki Eclipse składa fragmenty kodu. Nie wiem, czy to nadal działa, ale przypomniałem sobie, że można zdefiniować dowolne składane strefy, dodając specjalne komentarze, takie jak // [SECTION] czy coś. Może nadal działać w ostatnich wersjach Eclipse, więc spójrz.


146

Dla intellij / android studio jest świetne rozwiązanie.
Zacznij od:
//region Description
i zakończ:
//endregion

Skrót do tego znajduje się w menu, które można otworzyć za pomocą Command+ Alt+ T(Mac) lub Ctrl+ Alt+ T(Windows)

W razie potrzeby możesz również dodać własną linię, aby uzyskać dodatkową wizualną separację. Region można dowolnie zwężać i rozszerzać za pomocą przycisków +/-, jak każda inna funkcja. Możesz także nawigować między regionami za pomocą Command+ Alt+ Period( Ctrl+ Alt+ Period)

Źródło .

Przykład:

//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

Jest to niezwykle przydatne. Dziękuję Andrey. BTW Używam układu skrótów klawiaturowych zaćmienia i nie sądzę, aby skróty działały dla mnie, ale „// region” działa świetnie
ThinkBonobo

2
Nie widzę sposobu, aby to pokazało się w widoku struktury, więc nadal używam fałszywych pustych elementów członkowskich (wraz z pomijaniem nieużywanych ostrzeżeń).
Tom

1
czy istnieje sposób, aby pokazać te regiony w Android Studio (widok struktury)?
MiguelHincapieC

Link nie żyje; ten blog IntelliJ IDEA może być pomocnym źródłem informacji. Wspomina również o elementach składanych w stylu NetBeans <editor-fold ...> .
Franklin Yu,

najlepsza odpowiedź
Michał Ziobro

14

Eclipse definiuje adnotację @category javadoc (przewiń do sekcji oznaczonej „Obsługa kategorii”), która umożliwia filtrowanie według kategorii w widoku konspektu. Nie do końca to, czego chcesz. Jestem zaskoczony, że nikt nie napisał wtyczki Eclipse, która oferuje widok podobny do zrzutu ekranu.


Jednak w większości widoków Java możliwe jest filtrowanie składowych klas według ich kategorii, aby na przykład ukryć jako domyślne metody pobierające i ustawiające.
Riduidel,

nie mam pojęcia, dlaczego nie mogę używać @category w Android Studio, czy wiesz, co mogę zrobić, aby uzyskać takie samo zachowanie?
MiguelHincapieC,

6

Podobało mi się to również, gdy używałem xcode. W przypadku zaćmienia używam ctrl + o (szybki zarys), aby poruszać się po klasie Java.


6

Używanie niepotrzebnych komentarzy / znaczników w kodzie, aby pomóc w pracy, może nie być dobrą praktyką. Nie mam pojęcia o rozwoju xcode i java, ale wsparcie wszystkich głównych IDE w znajdowaniu członków bez żadnych specjalnych znaczników, takich jak zaćmienie, pokazuje metody i członków używających widoku konspektu, który można uruchomić za pomocą ctrl+OIntellij (którego wolę używać częściej na Macu i miał edycja społeczności) ma tę samą koncepcję konspektu i można do niej szybko uzyskać dostęp za pomocą (ctrl + f12). Chodzi mi więc o to, aby nie używać żadnych niepotrzebnych znaczników w kodzie, ponieważ wszystkie (lub przynajmniej dobre / rozsądne) IDE mogą to zrobić automatycznie.


2
Zgadzam się, znaczniki sekcji tylko dodają wizualnego bałaganu. Twoja klasa powinna być na tyle mocno skupiona, aby uczynić te rzeczy nieistotnymi.
Paul McKenzie,

15
Jasne, ale pogrupowanie metod w logiczne i wyodrębnione sekcje może pomóc narzucić wizualny porządek na czymś, co w przeciwnym razie byłoby płaską listą metod. Czasami nie wiesz dokładnie, którą metodę chcesz, i dobrze jest wziąć wszystkie powiązane metody naraz i mieć pojęcie, że widzisz pełny zakres powiązanego kodu.
Brian Rak

4

O ile wiem, nie ma czegoś takiego jak obsługiwana specyfikacja grupowania członków klas razem. Możesz użyć dowolnej konwencji komentarzy, ale są szanse, że nie będzie ona obsługiwana przez żadne narzędzie.

Lepiej jest pogrupować powiązane elementy członkowskie w oddzielne klasy przez dziedziczenie lub agregację. Jest to uważane za dobry styl OOP


5
Dzielenie części kodu wydaje się możliwe tylko w teorii. Na przykład weźmy klasę Client z atrybutami takimi jak nazwa i kolekcję „faktury”. Chciałbym móc podzielić to na sekcję „nazwa”, która zawiera metody pobierające / ustawiające dla nazwy, oraz sekcję „faktury”, która zawiera metody dodawania / usuwania faktur. Wydaje się niepraktyczne podzielenie ich na hierarchię klas, która może dodawać tylko jeden atrybut na klasę, tj. „NamedEntity”, „NameAndAddressEntity”, „Invoicable”, ...
Frederik

3

Oprócz podanej odpowiedzi Andreya, aby użyć // region // endregion, wstawiamy [BigAscii letters] [1] w głównych sekcjach kodu. Podczas szybkiego przewijania naprawdę się wyróżnia. Jedną z wad tego podejścia jest to, że nie mogę go wyszukać, więc musisz dodać wyszukiwane hasło tuż pod „banerem”, tak jak robię to poniżej.

Zablokować cytat

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

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


3

użyłbym javadoc ; lub użyj poniższego jako prostego „separatora” (pojedynczy lub 3 wiersze):

/** RecyclerOnItemClickListener */

/** 
 * RecyclerOnItemClickListener
 */

Tak więc w IDE pojawia się w innym kolorze niż dyskretnie komentowana szarość.


2

Nowoczesne środowisko IDE umożliwia przeglądanie kodu na wiele różnych sposobów, a nawet jego reorganizację. Eclipse umożliwia nawet wyświetlenie definicji kodu, na którym znajduje się kursor, w innym panelu.

Każda automatyczna reorganizacja Twojego kodu spowoduje uszkodzenie takiego znacznika.

Jeśli chcesz grupować, rozważ umieszczenie rzeczy należących do tej samej klasy, a rzeczy nie należących do różnych klas.


0

Jeśli możesz zgrupować swoje metody, zrób inną klasę specjalnie dla tej koncepcji, którą chcesz uchwycić w sekcji. Śmiało, tworzenie plików jest bezpłatne.


-18

W przypadku IntelliJ lubię:

        public void ________________INIT__________________() {};

ładnie wyglądający w strukturze pliku!


3
Wydaje się, że to bardzo złe rozwiązanie. Po co deklarować dodatkowe metody, gdy celem jest organizacja kodu?
nsg

1
Ma to na celu podzielenie całego pliku na segmenty w widoku Struktura.
Tycho Pandelaar

1
jest to jedyny, który wygląda naprawdę w android studio, proponuję jako odpowiedź i
użyję

14
Najgorsza rzecz, jaką kiedykolwiek widziałem !! i to jest PUBLICZNE! o_O
Cocorico,

3
To jedyna odpowiedź, która pojawia się w widoku struktury i działa w różnych środowiskach IDE. Uczyń to prywatnym i uśmiechnij się i znoś go, lub nie używaj go, jeśli ci się nie podoba, ale nie ukrywaj tej odpowiedzi przed innymi czytelnikami, odrzucając ją w zapomnienie.
Tom
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.