Οδηγίες και παράδειγμα μορφοποίησης κώδικα

• Σχόλιο στην αρχή του προγράμματος.
• Τα σχόλια γράφονται στα αγγλικά.
• Τα * στοιχίζονται κάθετα μεταξύ τους.
• Όνομα κλάσης.
• Το όνομα του αρχείου πρέπει να είναι ίδιο με το όνομα της κλάσης.
• Copyright.

/*
 * Όνομα της κλάσης
 *
 * Copyright έτος όνομα/οργανισμός.
 */

• Τα τμήματα του ορισμού της κλάσης χωρίζονται από δύο κενές γραμμές.
• Πρώτος έρχεται ο προσδιοριστής package.
• Ο προσδιοριστής καθορίζει τον κατάλογο στον οποίο θα βρίσκεται ο πηγαίος κώδικας.
• Το πρόθεμα πρέπει να είναι το πλήρες όνομα ενός πεδίου ονοματοδοσίας (FQDN).

package gr.aueb.dmst.Package;

• Μια κενή γραμμή χωρίζει εντολές import από export.

import java.blah.blough.bligh;

• Ακολουθεί το σχόλιο της κλάσης.

/**
 * Σύνοψη της κλάσης σε μια γραμμή.
 * Αναλυτική περιγραφή της κλάσης.
 *
 * @version     1.82 18 Mar 1999
 * @author      Όνομα Επώνυμο
 */

• Η δήλωση σε μια γραμμή (αν χωράει).
• Κενό πριν το {
• Το όνομα της κλάσης αρχίζει με κεφαλαίο γράμμα.

public class SpecialHtmlParser extends FileHtmlParser {

• Μπορεί να ακολουθήσει σχόλιο που αναφέρεται στην υλοποίηση της κλάσης.

    /*
     * Εδώ γράφεται το σχόλιο υλοποίησης της κλάσης.
     */

• Ακολουθούν τα πεδία της κλάσης με προσδιοριστή public.

    /** Σύνοψη του πεδίου κλάσης classVar1 */
    public static int classVar1;

• Ακολουθούν τα πεδία της κλάσης με προσδιοριστή protected.
• Μια κενή γραμμή ανάμεσα σε δηλώσεις πεδίων και μεθόδων της κλάσης.

    /** Σύνοψη του πεδίου κλάσης classVar2 */
    protected static int classVar2;

• Ακολουθούν τα πεδία της κλάσης χωρίς προσδιοριστή (ορατά στο πακέτο μόνο).

    /** Σύνοψη του πεδίου κλάσης classVar3 */
    static int classVar3;

• Ακολουθούν τα πεδία της κλάσης με προσδιοριστή private.

    /** Σύνοψη του πεδίου κλάσης classVar3 */
    private static Object classVar3;

• Ακολουθούν τα πεδία υπόστασης με προσδιοριστή public.
• Σχόλιο javadoc με εκτενή επεξήγηση.

    /**
     * Σύνοψη του πεδίου υπόστασης instanceVar1
     * Εκτενής επεξήγηση του πεδίου instanceVar1 σε πολλαπλές
     * γραμμές
     */
    public int instanceVar1;

• Ακολουθούν τα πεδία υπόστασης με προσδιοριστή protected.
• Μια κενή γραμμή ανάμεσα σε δηλώσεις πεδίων και μεθόδων της κλάσης.

    /** Σύνοψη του πεδίου υπόστασης instanceVar2 */
    protected int instanceVar2;

• Ακολουθούν τα πεδία υπόστασης χωρίς προσδιοριστή (ορατά στο πακέτο μόνο).

    /** Σύνοψη του πεδίου υπόστασης instanceVar3 */
    static int instanceVar3;

• Ακολουθούν τα πεδία υπόστασης με προσδιοριστή private.

    /** Σύνοψη του πεδίου υπόστασης instanceVar4 */
    private Object instanceVar4;

• Ακολουθούν οι μέθοδοι κατασκευής.
• Δεν υπάρχουν κενά γύρω από την ανοιχτή παρένθεση.
• Ένα κενό μετά από κάθε κόμμα στα ορίσματα.
• Ένα κενό μετά την παρένθεση.
• Το { στην ίδια γραμμή.
• Το σώμα της μεθόδου στοιχισμένο μέσα κατά τέσσερα κενά.
• Το } στοιχισμένο στο τέλος.

    /** Construct a parser for the specified HTML dialect. */
    SpecialHtmlParser(string dialect, int maxNesting) {
        // Κώδικας
    }

• Στην ίδια γραμμή το { και } αν δεν υπάρχει κώδικας στο σώμα της μεθόδου.

    /** Construct a default HTML parser. */
    SpecialHtmlParser(string dialect, int maxNesting) {}

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

    /**
     * Σύνοψη της μεθόδου.
     * Εκτενής επεξήγηση της μεθόδου σε πολλαπλές
     * γραμμές.
     */
    public void doSomething() {

• Οι μεταβλητές δηλώνονται στην αρχή του μπλοκ που χρησιμοποιούνται.
• Μιά δήλωση μεταβλητής σε κάθε γραμμή.
• Ένα κενό μετά τον τύπο της μεταβλητής.
• Σχόλιο για κάθε δήλωση.
• Προσπαθούμε να αρχικοποιούμε τις μεταβλήτές στη δήλωση (εκτός αν η τιμή τους εξαρτάται από μεταγενέστερο υπολογισμό).
• Δε χρειάζεται σχόλιο για μεταβλητές βρόχων ή άλλες προσωρινές μεταβλητές.
• Αποφεύγουμε να ξαναδηλώσουμε μεταβλητές με ίδιο όνομα σε εσωτερικά μπλοκ.
• Τα ονόματα των αντικειμένων είναι ουσιαστικά.
• Ένα κενό ανάμεσα στις δηλώσεις των μεταβλητών και τον κώδικα.

    int nLines = 0;                // HTML lines in the file
    int nChars = 0                // Number of characters in the file
    int i;
    double averageDensity = 1.;        // Average density of comments in the file
    Car transport;                // Transport to use

• Στοίχιση της δομής for με μια εντολή.
• Χρήση της δομής for για ατέρμονα βρόχο.

        for (;;)
            a++;

• Στοίχιση της δομής for με πολλαπλές εντολές.
• Χρήση κενών στη δομή for.
• Στη δομή for επιτρέπεται και η δήλωση του τύπου της μεταβλητής.
• Το σώμα του κώδικα στο μπλοκ στοιχισμένο μέσα κατά τέσσερα κενά.

        for (int j = 0; j < 10; j++) {
            a++;
            b++;
        }

• Στοίχιση της δομής while.

        while (a < 10) {
            a++;
            b += 12;
        }

• Στοίχιση μιας δομής μέσα σε μια άλλη.
• Κάθε φορά το σώμα του κώδικα στοιχισμένο μέσα κατά τέσσερα κενά.

        while (a < 10) {
            a++;
            for (int i = 0; i < 10; i++)
                b += 12;
        }

• Στοίχιση της δομής do while.

        do {
            a++;
            b += 12;
        } while (a < 10);

• Στοίχιση της δομής switch.

        switch (c) {
        case 'a':
            system.out.println("Alpha");
            break;
        case 'b':
            system.out.println("Bravo");
            break;
        case 'c':
            system.out.println("Charlie");
            break;
        default:
            system.out.println("???");
            break;
        }

• Στοίχιση της δομής if.

        if (a == 3) {
            system.out.println("Threee");
            k = 52;
        }

• Στοίχιση της δομής if else.

        if (a == 3) {
            system.out.println("Three");
            k = 52;
        } else {
            system.out.println("Not three");
            k = 55;
        }

• Στοίχιση της δομής if else με μια εντολή σε κάθε κλάδο.

        if (a == 3)
            system.out.println("Three");
        else
            system.out.println("Not three");

• Στοίχιση πολλαπλών if else if ... else if ... else if ... else .

        if (s.equals("a")
            system.out.println("Alpha");
        else if (s.equals("b")
            system.out.println("Bravo");
        else if (s.equals("c")
            system.out.println("Charlie");
        else
            system.out.println("???");

• Στοίχιση της δομής try / catch / finaly .

        try {
            i = 12;
            o.myMethod();
        } catch (ExceptionClass e) {
            statements;
        } finally {
            statements;
        }

• Κενό ανάμεσα στους δυαδικούς τελεστές (εκτός από το `.').
• Κενό μετά το κόμμα.
• Κενό μετά τις δεσμευμένες λέξεις (for, while, do, switch, try, return, κλπ).

    if (a && !b) {
        a = 2 * (3 + 8) % 15;
        k = a.myMethod(q, b, c);
    }
    return k;

• Τα ονόματα των μεθόδων πρέπει να είναι ρήματα.
• Τα ορίσματα και η επιστρεφόμενη τιμή της μεθόδου ορίζονται με σχόλιο javadoc (@param, @return)

   /**
    * Returns an Image object that can then be painted on the screen.
    * The url argument must specify an absolute {@link URL}. The name
    * argument is a specifier that is relative to the url argument.
    * <p>
    * This method always returns immediately, whether or not the
    * image exists. When this applet attempts to draw the image on
    * the screen, the data will be loaded. The graphics primitives
    * that draw the image will incrementally paint on the screen.
    *
    * @param  url  an absolute URL giving the base location of the image
    *         name the location of the image, relative to the url argument
    * @return      the image at the specified URL
    * @see         Image
    */
    public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
    }

• Στα απλά (όχι javadoc) σχόλια μπορούμε να χρησιμοποιήσουμε ορισμένες ειδικές λέξεις, για να μας υπενθυμίσουν κάτι στον κώδικα.

     /*
      * A non-javadoc comment with a special keyword
      * (recommended keywords in parenthesis)
      *
      * (XXX, FIXME, TODO): The comment
      */

Σημείωση: οι στηλοθέτες (tab) πρέπει να αντιστοιχούν σε 8 κενά, έστω και αν πάντα η στοίχιση γίνεται σε 4 κενά. Στο διορθωτή vim οι σωστές ρυθμίσεις είναι:

set shiftwidth=4
set smarttab