Μια σύντομη περίληψη των βέλτιστων πρακτικών κωδικοποίησης Java

με βάση τα πρότυπα κωδικοποίησης από την Oracle, το Google, το Twitter και το Spring Framework

Ο στόχος αυτού του άρθρου είναι να σας δώσει μια γρήγορη περίληψη των πράξεων που κάνουν και δεν κάνουν με άλλα λόγια να προτιμούν και να αποφεύγουν με βάση πρότυπα κωδικοποίησης από τεχνολογικούς γίγαντες όπως το Oracle, το Google, το Twitter και το Spring Framework.

Ίσως ή μήπως δεν συμφωνείτε με μερικές από τις βέλτιστες πρακτικές που παρουσιάζονται εδώ, και αυτό είναι απολύτως ωραίο όσο υπάρχει κάποιο πρότυπο κωδικοποίησης.

Γιατί πρότυπα κωδικοποίησης κατά πρώτο λόγο; Υπάρχουν πολλοί καλοί λόγοι αν το Google αυτό και θα σας αφήσω με την ακόλουθη εικόνα

Το πρότυπο κωδικοποίησης εγγράφων μπορεί να είναι μακρύ και βαρετό. Αυτό το άρθρο κεράσι συλλέγει τα κομμάτια από τις συμβάσεις κωδικοποίησης από το Google, το Oracle, το Twitter και την Άνοιξη και στόχος είναι να σας παρέχει ένα εύκολο στη χρήση και λιγότερο βαρετό σύνολο πρακτικών για να κάνετε τον κώδικα σας εύκολο να το διαβάσετε και να το διατηρήσετε.

Σχεδόν πάντα θα συμμετάσχετε σε ομάδες που εργάζονται σε υπάρχον λογισμικό και υπάρχει μια αρκετά καλή πιθανότητα ότι οι περισσότεροι από τους συγγραφείς έχουν αποχωρήσει ή έχουν μετατραπεί σε διαφορετικά έργα, αφήνοντας σας λανθάνοντα με τμήματα κώδικα που σας κάνουν να θέσετε υπό αμφισβήτηση την ανθρωπότητα.

Ας δούμε τις βέλτιστες πρακτικές από διάφορα πρότυπα κωδικοποίησης.

Αρχείο προέλευσης Java

Τα ακόλουθα θεωρούνται ως βέλτιστες πρακτικές όταν πρόκειται για αρχεία πηγής Java:

  • Το μήκος του αρχείου προέλευσης είναι μικρότερο από 2.000 γραμμές κώδικα
  • Το αρχείο προέλευσης είναι οργανωμένο με σχολιασμό τεκμηρίωσης, δήλωση πακέτου, ακολουθούμενη από σχόλιο κλάσης, εισαγωγές ομαδοποιημένες (στατική τελευταία), υπογραφή κλάσης / διεπαφής και ούτω καθεξής όπως φαίνεται κατωτέρω
πακέτο com.example.model;
/ **
 * Προοπτική χωρίς εφαρμογή για ανάγνωση από προγραμματιστές
 * οι οποίοι ενδεχομένως να μην έχουν τον πηγαίο κώδικα στο χέρι
 *
 * @author x, y, z
 * @date
 * @εκδοχή
 * @copyright
 *
 * /
εισαγωγή com.example.util.FileUtil;
/ *
 * Προαιρετικό σχόλιο ειδικά για την τάξη
 *
 * /
δημόσια τάξη SomeClass {
  // Στατικές μεταβλητές κατά σειρά ορατότητας
  δημόσιο στατικό τελικό ακέραιο PUBLIC_COUNT = 1;
  static τελικό ακέραιο PROTECTED_COUNT = 1;
  ιδιωτικό στατικό τελικό ακέραιο PRIVATE_COUNT = 1;
  // Μεταβλητές βαθμού κατά σειρά ορατότητας
  δημόσιο όνομα συμβολοσειράς.
  String postalCode;
  ιδιωτική διεύθυνση συμβολοσειράς.
  // Κατασκευαστής και υπερφορτωμένο σε διαδοχική σειρά
  publicClassClass () {}
  publicClassClass (όνομα στοιχειοσειράς) {
    this.name = όνομα;
  }}
  // Μέθοδοι
  δημόσιο String doSomethingUseful () {
    επιστρέψτε "Κάτι χρήσιμο".
  }}
  // getters, setters, equals, hashCode και toString στο τέλος
}}

Ονομασία

Τα ονόματα κλάσεων και διεπαφών είναι CamelCase και συνιστάται να χρησιμοποιείτε ολόκληρη τη λέξη και να αποφεύγετε ακρωνύμια / συντμήσεις. Για παράδειγμα, κατηγορία Raster ή class ImageSprite

  • Πακέτο - ονόματα com.deepspace επάνω από com.deepSpace ή com.deep_space
  • Τα αρχεία - ονόματα είναι CamelCase και τέλος με .java που ταιριάζουν με το όνομα της κλάσης. Υπάρχει μια δημόσια τάξη ανά αρχείο με κάθε κλάση ανώτερου επιπέδου στο αρχείο του
  • Μέθοδος - τα ονόματα πρέπει να είναι ρήματα σε μικτή περίπτωση με κάθε εσωτερική λέξη με κεφαλαία γράμματα, για παράδειγμα εκτέλεση (); ή runFast ();
  • Σταθερά - πρέπει να είναι κεφαλαία με "_" διαχωρίζοντας κάθε λέξη για παράδειγμα int MIN_WIDTH = 44; και int MAX_WIDTH = 99.
  • Μεταβλητή - ένα όνομα που λέει στον αναγνώστη του προγράμματος τι αντιπροσωπεύει η μεταβλητή δηλαδή αν αποθηκεύετε μια δοκιμαστική τάξη, στη συνέχεια επιλέγετε βαθμό vs var1. Διατηρήστε τα ονόματα των μεταβλητών, αποφεύγοντας τα μεταδεδομένα.
// Προτιμήστε (✔) - σύντομα ονόματα μεταβλητών και περιγράψτε τι αποθηκεύει
int schoolId;
int [] filteredSchoolIds;
int [] uniqueSchooldIds.
Χάρτης <Ακέραιος, Χρήστης> χρήστεςById;
Τιμή στοιχειοσειράς.
// Αποφύγετε (x) - Πολύ λεπτομερή ονομαστική μεταβλητή
int schoolIdentificationNumber;
int [] userProvidedSchoolIds;
int [] schoolIdsAfterRemovingDuplicates;
Χάρτης <Ακέραιος, Χρήστης> idToUserMap;
String value string;

Θυμηθείτε - το όνομα της μεταβλητής πρέπει να είναι σύντομο και να λέει εύκολα στον αναγνώστη τι αξία αντιπροσωπεύει. Χρησιμοποιήστε την κρίση σας.

Προτιμήστε & αποφύγετε

Η μορφοποίηση και η εσοχή αφορούν την οργάνωση του κώδικα, ώστε να είναι εύκολη η ανάγνωση, και περιλαμβάνει απόσταση, μήκος γραμμής, αναδιπλώσεις και διαλείμματα κ.ο.κ.

  • Εσοχή - Χρησιμοποιήστε 2 ή 4 διαστήματα και μείνετε συνεπής
  • Μήκος γραμμής - Έως 70 έως 120 χαρακτήρες ανάλογα με την επίδραση της αναγνωσιμότητας. Είναι σημαντικό να εξαλείψετε την ανάγκη για οριζόντια κύλιση και να τοποθετήσετε διαλείμματα γραμμής μετά από κόμμα και χειριστή.

Μέθοδοι - Παρακάτω παρουσιάζονται οι βέλτιστες πρακτικές

// Προτιμήστε (✔) Οι διαχωριστικές γραμμές είναι αυθαίρετες και σπάστε μετά από κόμμα.
String downloadAnInternet (Διαδίκτυο, σωλήνες,
    Ιστολόγια Blogosphere, Ποσό  εύρος ζώνης) {
  tubes.download (internet);
}}
// Αποφύγετε (x) Η μέθοδος Hard to diff διαφέρει στο σώμα της μεθόδου
String downloadAnInternet (Διαδίκτυο, σωλήνες,
    Ιστολόγια Blogosphere, Ποσό  εύρος ζώνης) {
    tubes.download (internet);
}}
// Προτιμήστε (✔) Προσθέστε 8 (διπλά από 2 ή 4) κενά για βαθιά εσοχή
ιδιωτικό στατικό συγχρονισμένο horkingLongMethodName (int anArg,
        Object anotherArg, String yetAnotherArg,
        Object καιStillAnother) {
  ...
}}
// Προτιμήστε (✔ Easy) Εύκολη σάρωση και πρόσθετο διάστημα στήλης.
public String downloadAnInternet (
    Διαδίκτυο,
    Σωλήνες σωλήνες,
    Blogs Blogs,
    Ποσό  εύρος ζώνης) {
  tubes.download (internet);
  ...
}}
Μια δοκιμή μονάδας θα είχε πιάσει αυτό το

Εάν-επιταγές - IMO γραφή καλά μορφοποιημένο κώδικα καθιστά εύκολο να εντοπίσει τα λάθη και τα λάθη στον συντάκτη και τους αναθεωρητές κώδικα, δείτε παρακάτω:

// Αποφύγετε (x) Μην παραλείψετε {}
αν (προϋπόθεση)
  δήλωση;
// Αποφύγετε (x)
αν (x <0) αρνητικό (x);
// Αποφύγετε (x)
αν (a == b && c == d) {
...
}}
// Προτιμήστε (✔)
αν ((a == b) && (c == d)) {
...
}}
// Προτιμήστε (✔)
εάν (προϋπόθεση) {
  δηλώσεις ·
} else if (condition) {
  δηλώσεις ·
} else if (condition) {
  δηλώσεις ·
}}
// Αποφύγετε (x)
αν ((condition1 && condition2)
    || (condition3 && condition4)
    ||! (condition5 && condition6)) {// ΚΑΤΑΡΡΥΘΜΙΣΕΙΣ
    Κάνε κάτι για αυτό(); // ΚΑΝΕΤΕ ΑΥΤΗ ΤΗΝ ΓΡΑΜΜΗ ΕΥΚΟΛΙΑ ΜΑΚΡΙΑ
}}
// Προτιμήστε (✔)
αν ((condition1 && condition2)
        || (condition3 && condition4)
        ||! (condition5 && condition6)) {
    Κάνε κάτι για αυτό();
}}

Τερματικός χειριστής - Και παρακάτω συνιστώνται πρακτικές

alpha = (aLongBooleanExpression); βήτα: γάμα;
alpha = (aLongBooleanExpression); βήτα
        : γ.
alpha = (aLongBooleanExpression)
        ; βήτα
        : γ.

Switch - Όταν πρόκειται να αλλάξετε τη βέλτιστη πρακτική

  • Πάντα έχετε μια προεπιλεγμένη περίπτωση ακόμη και χωρίς κωδικό
  • Χρησιμοποιήστε / * πέφτει μέσω * / για να υποδείξετε ότι ο έλεγχος πέφτει στην επόμενη περίπτωση
διακόπτης (κατάσταση) {
  περίπτωση ABC:
    δηλώσεις ·
  / * πέφτει μέσω * /
  περίπτωση DEF:
    δηλώσεις ·
    Διακοπή;
  Προκαθορισμένο:
    δηλώσεις ·
     Διακοπή;
}}

Μηνύματα εξαίρεσης - Όταν ρίχνετε μια εξαίρεση εδώ είναι δείγματα καλών και ανεπαρκώς χαραγμένων μηνυμάτων.

// Αποφύγετε (x) - Δεν είναι εύκολο να διαβάσετε
("Αποτυχία επεξεργασίας αιτήματος" + request.getId ())
    + "για το χρήστη" + user.getId () + "ερώτημα:" + query.getText ()
    + "" ").
// Προτιμήστε (✔ -) - Αρκετά ευκολότερη στην ανάγνωση
να ρίξει νέα παράνομη εκκένωση ("Αποτυχία επεξεργασίας"
    + "αίτημα" + request.getId ()
    + "για χρήστη" + user.getId ()
    + "ερώτημα:" + query.getText () + "'");

Επεξεργαστές και ρεύματα - Τα ρεύματα γίνονται όλο και πιο συνηθισμένα και μερικές φορές μπορεί να είναι πολύ περίπλοκα ως εκ τούτου, είναι σημαντικό να χαράξουμε για εύκολη ανάγνωση.

Jsme αποθε orig
Επεξεργαστής  modules = ImmutableList.  builder () Προσθήκη (νέο LifecycleModule ())
    .add (νέο appLauncherModule ()). addAll (application.getModules ()) build ();
// Προτιμήστε (✔ -) - Αρκετά ευκολότερη στην ανάγνωση
Ενότητες  modules = ImmutableList.  builder ()
    .add (νέο LifecycleModule ())
    .add (νέο AppLauncherModule ())
    .addAll (application.getModules ())
    .χτίζω();
Απλά ακολουθήστε ένα πρότυπο κωδικοποίησης - οποιοδήποτε πραγματικά

Δηλώσεις και αναθέσεις - Συνιστάται μία δήλωση ανά γραμμή, καθώς ενθαρρύνει τα σχόλια όπως φαίνεται παρακάτω.

// Προτιμήστε (✔)
int επίπεδο? // level indent
int sizeMeter; // μέγεθος πίνακα
// Αποφύγετε (x) υπέρ των παραπάνω
επίπεδο int, sizeMeter;
// Προτιμήστε () - Συμπεριλάβετε μονάδα σε μεταβλητό όνομα ή τύπο
long pollIntervalMs;
int fileSizeGb;
Ποσό <Ακέραιος αριθμός, Δεδομένα> μέγεθος αρχείου;
// Αποφύγετε (x) τύπους ανάμιξης
int foo, fooarray [];
// Αποφύγετε (x) - Μη διαχωρίζετε με κόμμα
Format.print (System.out, "σφάλμα"), έξοδος (1);
// Αποφύγετε (x) πολλαπλή ανάθεση
fooBar.fChar = barFoo.lchar = 'c';
// Αποφύγετε (x) τις ενσωματωμένες αναθέσεις σε προσπάθεια να αυξήσετε την απόδοση // ή να αποθηκεύσετε μια γραμμή. Είμαι ένοχος να το κάνω αυτό :(
d = (a = b + c) + r.
// Προτιμήστε (✔) παραπάνω
a = b + c.
d = a + r.
// Προτιμήστε (✔)
String [] args
// Αποφύγετε (x)
Το string args []
// Προτιμήστε (✔) Μεγάλη χρήση "L" αντί "l" για να αποφύγετε τη σύγχυση με το 1
μεγάλο χρονικό όριο = 3000000000L;
// Αποφύγετε (x) - Είναι δύσκολο να πείτε ότι το τελευταίο γράμμα είναι l και όχι το 1
μεγάλο χρονικό όριο = 3000000000l;

Καταχωρίστε τις δηλώσεις μόνο στην αρχή των μπλοκ (Ένα μπλοκ είναι κώδικας που περιβάλλεται από σγουράκια {και}). Μην περιμένετε να δηλώσετε μεταβλητές μέχρι την πρώτη χρήση τους. μπορεί να συγχέει τον απρόσεκτο προγραμματιστή και να παρεμποδίζει τη φορητότητα του κώδικα εντός του πεδίου εφαρμογής.

// Προτιμήστε (✔) να δηλώσετε στην αρχή του μπλοκ.
δημόσιο κενό doSomething () {
  int whatIRepresent; // αρχή του μπλοκ μεθόδου
  εάν (προϋπόθεση) {
    int someFlag; // αρχή του μπλοκ "if"
    ...
  }}
}}

Είναι επίσης σημαντικό να αποφεύγετε τις τοπικές δηλώσεις που κρύβουν τις δηλώσεις των υψηλότερων επιπέδων και να αποφεύγετε συγχύσεις όπως φαίνεται παρακάτω

int count?
...
δημόσιο κενό doSomething () {
  εάν (προϋπόθεση) {
    int count? // ΑΠΟΦΥΓΕΙ!
    ...
  }}
  ...
}}

Διαχωρισμός διαστημάτων & γραμμών - Αποφύγετε τον πειρασμό να αποθηκεύσετε 1-2 γραμμές κώδικα σε βάρος της αναγνωσιμότητας. Εδώ είναι όλες οι βέλτιστες πρακτικές όταν πρόκειται για απόσταση και κενές γραμμές (Ένας λευκός χώρος κάνει τη διαφορά)

  • Μία (1) κενή γραμμή ανάμεσα στις μεθόδους και οι προγραμματιστές της Άνοιξης συνιστούν δύο (2) κενές γραμμές μετά από κατασκευαστές, στατικό μπλοκ, πεδία και εσωτερική κλάση
  • Οι χειριστές διαστημικού ταμπόν δηλ. Χρήση int foo = a + b + 1. πάνω από το int foo = a + b + 1;
  • Διαχωρίστε όλους τους δυαδικούς χειριστές εκτός από "." Από τους τελεστές χρησιμοποιώντας ένα κενό
  • Το ανοιχτό στήριγμα "{" εμφανίζεται στο τέλος της ίδιας γραμμής με τη δήλωση ή τη μέθοδο δήλωσης και το στήριγμα κλεισίματος "}" ξεκινά μια γραμμή από μόνη της χαραγμένη
// Προτιμήστε (✔) - Διαστήματος μετά από "ενώ" και πριν "("
ενώ (αληθής) {
  ...
}}
// Αποφύγετε (x) - Σε αντίθεση με τα παραπάνω δεν υπάρχει χώρος
ενώ (αληθής) {
  ...
}}
// Προτιμήστε () - Δεν υπάρχει χώρος μεταξύ του "doSomething" και του "("
δημόσιο κενό doSomething () {
  ...
}}
// Αποφύγετε (x) - Σε αντίθεση με τον παραπάνω χώρο
δημόσιο κενό doSomething () {
  ...
}}
// Προτιμήστε (✔) - Προσθέστε ένα κενό μετά από ένα επιχείρημα
δημόσιο κενό doSomething (int a, int b) {
  ...
}}
// Προτιμήστε (✔) - Διάστημα μεταξύ τελεστή και χειριστών (δηλαδή +, =)
α + = c + d.
α = (α + β) / (c * d).
ενώ (d ++ = s ++) {
  n ++;
}}

Τεκμηρίωση και σχόλια

Αξίζει να σημειωθεί ότι σχεδόν όλος ο κώδικας πηγαίνει αλλαγές καθ 'όλη τη διάρκεια της ζωής του και θα υπάρξουν στιγμές που εσείς ή κάποιος προσπαθεί να καταλάβει τι πρόκειται να κάνει ένα σύνθετο μπλοκ κώδικα, μια μέθοδος ή μια κλάση εκτός αν περιγράφεται σαφώς. Η πραγματικότητα είναι σχεδόν πάντα όπως ακολουθεί

Υπάρχουν φορές που το σχόλιο σε ένα σύνθετο κομμάτι κώδικα, μέθοδο, τάξη δεν προσθέτει καμία αξία ή εξυπηρετεί το σκοπό του. Αυτό συμβαίνει συνήθως όταν σχολιάζετε για χάρη του.

Τα σχόλια θα πρέπει να χρησιμοποιούνται για την επισκόπηση των κωδικών και να παρέχουν πρόσθετες πληροφορίες που δεν είναι άμεσα διαθέσιμες στον ίδιο τον κώδικα. Ας αρχίσουμε. Υπάρχουν δύο είδη σχολίων

Εφαρμογή Σχόλια - πρόκειται να σχολιάσουν τον κώδικα ή να σχολιάσουν μια συγκεκριμένη εφαρμογή του κώδικα.

Τα Σχόλια Τεκμηρίωσης - αποσκοπούν να περιγράψουν τις προδιαγραφές του κώδικα από μια προοπτική χωρίς εφαρμογή που θα διαβαστούν από προγραμματιστές οι οποίοι ενδέχεται να μην έχουν αναγκαστικά τον πηγαίο κώδικα.

Η συχνότητα των σχολίων αντανακλά μερικές φορές την κακή ποιότητα του κώδικα. Όταν αισθάνεστε υποχρεωμένοι να προσθέσετε ένα σχόλιο, σκεφτείτε να ξαναγράψετε τον κώδικα για να το καταστήσετε σαφέστερο.

Είδη σχολίων εφαρμογής

Υπάρχουν τέσσερις (4) τύποι παρατηρήσεων εφαρμογής όπως φαίνεται παρακάτω

  • Αποκλεισμός σχολίου - δείτε το παρακάτω παράδειγμα
  • Σχόλιο μιας γραμμής - όταν το σχόλιο δεν είναι μεγαλύτερο από μια γραμμή
  • Παρατηρητικά σχόλια - Πολύ σύντομο σχόλιο μεταφέρθηκε στο δεξιό άκρο
  • Σχόλιο τέλος της γραμμής - ξεκινά ένα σχόλιο που συνεχίζει στη νέα γραμμή. Μπορεί να σχολιάσει μια πλήρη γραμμή ή μόνο μια μερική γραμμή. Δεν πρέπει να χρησιμοποιείται σε διαδοχικές πολλαπλές γραμμές για σχόλια κειμένου. Ωστόσο, μπορεί να χρησιμοποιηθεί σε διαδοχικές πολλαπλές γραμμές για να σχολιάσει τμήματα του κώδικα.
// Αποκλεισμός σχολίου
/ *
 * Χρήση: Παρέχει περιγραφή αρχείων, μεθόδων, δομών δεδομένων
 * και αλγόριθμοι. Μπορεί να χρησιμοποιηθεί στην αρχή κάθε αρχείου και
 * πριν από κάθε μέθοδο. Χρησιμοποιείται για μακρά σχόλια που δεν ταιριάζουν με a
 * μία γραμμή. 1 Λευκή γραμμή για να προχωρήσετε μετά το σχόλιο του μπλοκ.
 * /
// Σχόλιο μιας γραμμής
εάν (προϋπόθεση) {
 / * Χειριστείτε την κατάσταση. * /
  ...
}}
// Παρατηρούμενο σχόλιο
αν (a == 2) {
 επιστρέψτε TRUE. /* ειδική περίπτωση */
} else {
 Η επιστροφή είναι η πρώτη (a); / * λειτουργεί μόνο για περιττό a * /
}}
// Σχόλιο στο τέλος της γραμμής
εάν (foo> 1) {
  // Κάντε διπλό flip.
  ...
} else {
  επιστροφή ψευδής? // Εξηγήστε γιατί εδώ.
}}
// αν (bar> 1) {
//
// // Κάντε ένα τριπλό flip.
// ...
//}
//αλλού
// return false;

Τα σχόλια τεκμηρίωσης (δηλ. Javadoc)

Το Javadoc είναι ένα εργαλείο που δημιουργεί τεκμηρίωση HTML από τον κώδικα Java χρησιμοποιώντας τα σχόλια που ξεκινούν με / ** και τελειώνει με το * / - Βλέπε Wikipedia για περισσότερες λεπτομέρειες σχετικά με τον τρόπο λειτουργίας του Javadoc ή απλά διαβάστε.

Ακολουθεί ένα παράδειγμα του Javadoc

/ **
 * Επιστρέφει ένα αντικείμενο εικόνας που μπορεί στη συνέχεια να ζωγραφιστεί στην οθόνη.
 * Το όρισμα url πρέπει να καθορίζει μια απόλυτη {@link URL}. Το όνομα
 * argument είναι ένας προσδιοριστής που είναι σχετικός με το όρισμα url.
 * 

 * Αυτή η μέθοδος επιστρέφει πάντα αμέσως, ανεξάρτητα από το εάν ή όχι  * Υπάρχει εικόνα. Όταν αυτή η μικροεφαρμογή επιχειρεί να σχεδιάσει την εικόνα  * στην οθόνη, τα δεδομένα θα φορτωθούν. Τα πρωτότυπα γραφικών  * που σχεδιάζουν την εικόνα θα ζωγραφίζουν σταδιακά στην οθόνη.  *  * @param url μια απόλυτη διεύθυνση URL δίνοντας τη βάση της εικόνας  * @param ονομάστε τη θέση της εικόνας, σε σχέση με το όρισμα url  * @ επιστρέψτε την εικόνα στην καθορισμένη διεύθυνση URL  * @ βλέπε Εικόνα  * /  δημόσια Εικόνα getImage (URL url, όνομα συμβολοσειράς) {         προσπαθήστε {             επιστροφή getImage (νέα διεύθυνση URL (διεύθυνση URL, όνομα));         } αλίευση (MalformedURLException ε) {             επιστροφή null;         }}  }}

Και τα παραπάνω θα οδηγήσουν σε μια HTML ως εξής όταν το javadoc τρέχει με τον κώδικα που έχει τα παραπάνω

Δείτε εδώ για περισσότερα

Εδώ είναι μερικές ετικέτες κλειδιών που μπορείτε να χρησιμοποιήσετε για να βελτιώσετε την ποιότητα της παραγόμενης τεκμηρίωσης Java.

@author => @author Raf
@code => {@ κωδικός A  C}
@deprecated => @αναγνωρισμένο μήνυμα απόρριψης
@exception => @exception IOException ρίχνονται όταν
@link => {@link package.class # ετικέτα μέλους}
@param => @param parameter-name description
@return => Τι επιστρέφει η μέθοδος
@see => @βλέπε "συμβολοσειρά" Ή @βλέπε > 
@since => Για να δηλώσετε την έκδοση όταν προστίθεται μια προσπελάσιμη από το κοινό μέθοδος

Για πλήρη λίστα και λεπτομερέστερη περιγραφή, δείτε εδώ

Το πρότυπο κωδικοποίησης του Twitter συμβουλεύει τη χρήση της ετικέτας @author

Ο κώδικας μπορεί να αλλάξει τα χέρια πολλές φορές στη διάρκεια της ζωής του, και αρκετά συχνά ο αρχικός συγγραφέας ενός αρχείου προέλευσης είναι άσχετος μετά από αρκετές επαναλήψεις. Θεωρούμε ότι είναι καλύτερο να εμπιστευόμαστε την ιστορία της δέσμευσης και τα αρχεία OWNERS για να καθορίσουμε την ιδιοκτησία ενός σώματος κώδικα.

Ακολουθούν παραδείγματα για το πώς θα μπορούσατε να γράψετε ένα σχόλιο τεκμηρίωσης που είναι διορατικό όπως περιγράφεται στο πρότυπο κωδικοποίησης του Twitter

// Κακό.
// - Ο doc δεν λέει τίποτα ότι η δήλωση της μεθόδου δεν το έκανε.
// - Αυτή είναι η 'doc filler'. Θα περάσει ελέγχους στυλ, αλλά
δεν βοηθά κανέναν.
/ **
 * Διαχωρίζει μια συμβολοσειρά.
 *
 * @param s Μια συμβολοσειρά.
 * @return Μια λίστα συμβολοσειρών.
 * /
Λίστα  split (String s);
// Καλύτερα.
// - Γνωρίζουμε ποια είναι η μέθοδος που χωρίζει.
// - Ακόμη κάποια απροσδιόριστη συμπεριφορά.
/ **
 * Διαχωρίζει μια συμβολοσειρά σε κενό.
 *
 * @param s Η συμβολοσειρά για να χωριστεί. Μια συμβολοσειρά {@code null} αντιμετωπίζεται ως κενή συμβολοσειρά.
 * @return Μια λίστα με τα τμήματα της εισόδου που οριοθετούνται από το κενό.
 * /
Λίστα  split (String s);
// Μεγάλος.
// - Καλύπτει ακόμα μια ακραία θήκη.
/ **
 * Διαχωρίζει μια συμβολοσειρά σε κενό. Επαναλαμβανόμενοι χαρακτήρες
 * έχουν καταρρεύσει.
 *
 * @param s Η συμβολοσειρά για να χωριστεί. Μια συμβολοσειρά {@code null} αντιμετωπίζεται ως κενή συμβολοσειρά.
 * @return Μια λίστα με τα τμήματα της εισόδου που οριοθετούνται από το κενό.
 * /
Λίστα  split (String s);

Είναι σημαντικό να είσαι επαγγελματίας όταν πρόκειται να γράψεις σχόλια

// Αποφύγετε (x)
// Μισώ xml / σαπούνι τόσο πολύ, γιατί δεν μπορεί να το κάνει αυτό για μένα !?
προσπαθήστε {
  userId = Integer.parseInt (xml.getField ("id")).
} αλίευση (NumberFormatException ε) {
  ...
}}
// Προτιμήστε (✔)
// TODO (Jim): Η επικύρωση του πεδίου του Tuck σε μια βιβλιοθήκη.
προσπαθήστε {
  userId = Integer.parseInt (xml.getField ("id")).
} αλίευση (NumberFormatException ε) {
  ...
}}

Και είναι σημαντικό να μην ξεχνάτε να μην τεκμηριώνετε την παράκαμψη της μεθόδου εκτός εάν η εφαρμογή έχει αλλάξει.

Και εδώ είναι μερικά ακόμη σημεία που πρέπει να θυμάστε

  • Αποφύγετε τις εισαγωγές μπαλαντέρ - όπως περιγράφεται στα πρότυπα κωδικοποίησης του Twitter, καθιστά την πηγή της κλάσης λιγότερο σαφής. Δουλεύω σε μια ομάδα με ένα συνδυασμό χρηστών Eclipse και IntelliJ και ανακάλυψα ότι το Eclipse αφαιρεί τις εισαγωγές μπαλαντέρ και το IntelliJ το παρουσιάζει. Υπάρχει πιθανώς μια επιλογή να το απενεργοποιήσετε, απλώς ήθελε να επισημάνει την προεπιλογή για τα δύο.
  • Πάντα να χρησιμοποιείτε σχολιασμό @Override όταν παραβλέπεται
  • Ενθαρρύνετε τη χρήση του @Nullable όταν ένα πεδίο ή μέθοδος επιστρέφει null
  • Χρησιμοποιήστε ειδικά σχόλια για τη μελλοντική δουλειά και μην ξεχάσετε να αφήσετε μια αναφορά στον εαυτό σας, ώστε άλλοι να ξέρουν ποιοι να θέσουν την ερώτησή τους Y αντί να μαντέψουν, να την καταργήσουν ή να ελέγξουν την ευθύνη του git για να βρουν ποιος το πρόσθεσε. Ορισμένες συσκευές IDE, όπως το Eclipse και το IntelliJ, βοηθούν επίσης στην καταχώρισή τους για εύκολη πρόσβαση καθώς και υπενθύμιση.
// FIXME (Raf): Ένα ενεργό μήνυμα περιγράφει τι πρέπει να γίνει
// TODO (Raf): Ένα ενεργό μήνυμα περιγράφει τι πρέπει να γίνει

Το τέλος παιχνίδι είναι να γράψω κώδικα που καθιστά τη ζωή των μελλοντικών δημιουργών και συντηρητών εύκολη.

Το τελικό παιχνίδι

Άλλα σχετικά αναγνωστικά υλικά

Μια λίστα σχετικών άρθρων που σχετίζονται με τη σύνταξη κώδικα που είναι καθαρός, καλά δομημένος, εύκολος στην ανάγνωση και συντηρήσιμος. Αν θέλετε να διαβάσετε περισσότερα, σίγουρα προτείνετε τα παρακάτω

και μια άλλη καλή λίστα συμβουλών για να γράψετε καθαρό κώδικα