Specifiche Sun

Introduzione, Nomi di File e Organizzazione dei File

 

1. Introduzione

1.0. Nota del traduttore
Questo documento rappresenta una libera traduzione in lingua italiana del documento "Java Code Conventions" distribuito da Sun Microsystems.
La traduzione del testo è integrale, inclusi i codici di esempio (dove possibile), ed è stata curata da Angelo Carpenzano (http://web.tiscalinet.it/acarpenzano/).
Chiunque rilevasse errori, imperfezioni o imprecisioni, può spedire le sue note all'indirizzo a.carpenzano@softwareplanet.net.

1.1. Perché abbiamo convenzioni per il codice
Si stima che circa l'80% del costo di una porzione di software sia dovuto alla manutenzione e difficilmente tale manutenzione viene tenuta dall'autore originale per tutta la durata del programma.
Le convenzioni aumentano la leggibilità del software, permettendo ai programmatori di comprendere un nuovo codice più velocemente e facilmente.
Affinché le convenzioni funzionino, è necessario che ogni persona che scrive software si conformi ad esse.

1.2. Riconoscimenti
Questo documento riflette gli standard di codifica per il linguaggio Java presentati nel Java Language Specification, da Sun Microsystems, Inc.
I maggiori contributi vengono da Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, Kathy Walrath e Scott Hommel.
Questo documento è mantenuto da Scott Hommel. I commenti devono essere inviati a shommel@eng.sun.com

2. Nomi di file

Questa sezione elenca i nomi e i suffissi di file usati comunemente.

2.1. Suffissi dei file
Java Software usa i seguenti suffissi di file:

TIPO DI FILE

SUFFISSO

Sorgente Java

.java

Bytecode Java

.class


2.2. Nomi di file comuni
I nomi di file usati frequentemente includono:

NOME FILE

USO

GNUmakefile

Nome preferito per i makefile.

README

Nome preferito per il file che riassume il contenuto di una particolare directory.


 
3. Organizzazione dei file

Un file consiste di sezioni che dovrebbero essere separate da linee bianche e un commento opzionale che identifica ogni sezione.
File più lunghi di 2000 linee sono ingombranti e devono essere evitati.
Per un esempio di un programma Java formattato propriamente, vedi "Esempio di File Sorgente Java" alla fine del documento.

3.1. File sorgenti
Ogni file sorgente Java contiene un singola classe pubblica o un'interfaccia. Quando ci sono classi e interfacce private associate con una classe pubblica, è possibile inserirle nello stesso file sorgente della classe pubblica. La classe pubblica deve essere la prima classe o interfaccia nel file.

I file sorgenti Java hanno la seguente struttura:
Commenti d'inizio
Istruzioni di package e import
Dichiarazioni di classe e interfaccia

3.1.1. Commenti d'inizio
Tutti i file sorgenti devono iniziare con un commento in stile C, che elenca il nome della classe, informazioni sulla versione, data e informazioni di copyright:

/*
 * Nome della classe
 *
 * Informazioni di versione
 *
 * Data
 *
 * Informazioni di copyright
 */


3.1.2. Istruzioni di package e import
La prima linea non-commento di molti file sorgenti Java è l'istruzione package, che può essere seguita da istruzioni import. Ad esempio:

package java.awt;
import java.awt.peer.CanvasPeer;

3.1.3. Dichiarazioni di classe e interfaccia
La seguente tabella descrive le parti della dichiarazione di una classe o interfaccia, nell'ordine in cui devono apparire.

 

Parte della dichiarazione di classe/interfaccia

Note

1

Commento di documentazione della classe/interfaccia (/**…*/).

Vedi la successiva sezione "Commenti di documentazione" per ulteriori informazioni.

2

Istruzione class o interface

 

3

Commento di implementazione della classe/interfaccia, se necessario.

Questo commento deve contenere  informazioni generali sulla classe o interfaccia, che non sono appropriate per il commento di documentazione.

4

Variabili di classe (static)  

Prima le variabili di classe public, poi quelle protected, poi quelle a livello di package (senza modificatori di accesso) e infine quelle private.

5

Variabili istanza

Prima quelle public, poi quelle protected, quelle a livello di package (senza modificatori di accesso), e infine quelle private.

6

Costruttori

 

7

Metodi

Questi metodi devono raggruppati in funzione della loro funzionalità piuttosto che in base a regole di visibilità o accessibilità. Ad esempio, un metodo di classe privato può stare tra due metodi istanza pubblici. L'obbiettivo è rendere più semplice la lettura e la comprensione del codice.

 

Torna all'indice Generale del corso di Specifiche Sun di Software Planet