Styleguide für die Softwareentwicklung TKP: Styleguide für die Softwareentwicklung

Datum: 3.7.1995
Styleguide

Autoren:

Patrick Steiner pas@informatik

Stichworte:

Kommentare
Dateiaufteilung
Variablenschreibweise

Zusammenfassung:

Duch die Nutzung festgelegter Styles ist es bei einer Gruppenarbeit, wie der im Projekt SAUS, einfacher, sich in fremde Sourcen einzuarbeiten. Daher sollte festgelegt werden, wie z.B. Kommentare in Programmen oder die Aufteilung auf mehrere Dateien zu gestalten sind.

Folien:

Folie: Warum etwas festlegen

Programmcode wird besser lesbar
Einfacher in fremden Programmcode einarbeitbar
Verwendung von Schnittstellen

Folie: Was sollte festgelegt werden?

Welche Programmiersprache
Welche Sprache f"ur Kommentare
Einführende Kommentare in Files
Einführende Kommentare vor Funktionen
Zeilenkommentare in Programmen
Schreibweise von Variablen, und Datentypen
Schreibweise der Dateinamen
Versionsverwaltung

Folie: Einführende Kommentare

Am Anfang jeder Datei ein einf"uhrender Kommentar:

/////////////////////////////////////////// // // FILE: // XXX.cc // // DESCRIPTION: // [Grobbeschreibung der Funktionali- // taeten] // // $Author: patrick $ $Revision: 1.4 $ // $Date: 1995/06/01 06:58:07 $ // // $Log: folien.tex,v $ % Revision 1.4 1995/06/01 06:58:07 patrick % Schriftgroesse veraendert % % Revision 1.3 1995/05/31 17:18:09 patrick % Endgueltige Version % % Revision 1.2 1995/05/15 18:09:16 patrick % Neue Ideen von Jens und Jan eingebaut % // /////////////////////////////////////////////

Folie: Kommentare für Funktionen

vollst"andige Prototypen in die Definitionsdatei
Vor jede Funktion ein Kommentar mit:
- Funktionsname
- Aufgabe der Funktion
- Argumentebeschreibung
- mögliche Rückgabewerte
- Datum letzte Änderung

////////////////////////////////////////////// // // Funktion: int setValue(double val) // Aufgabe: Wert setzen // Argumente: val : zu setzender Wert // Rueckgabewerte: 1 wenn OK // 0 sonst // Letzte Aenderung: 11.04.1995 // //////////////////////////////////////////////

Folie: Zeilenkommentare

Nichttriviale Zeilen müssen kommentiert werden.
Kommentar über zu kommentierender Zeile.
Kommentar nicht zu lang.

// Farbwert aus Tabelle holen cd = colTable[ x >> XSHIFT ][ y >> YSHIFT ];

Folie: Schreibweisen

Konstanten \& Globale Variablen:
- am Anfang der Datei
- Großschrift
Lokale Variablen:
- jede f"ur sich allein
- so dicht wie möglich am Ort der Verwendung
- erster Buchstabe Kleinschrift
Klassen:
- pro Definitionsdatei nur eine Klasse
- großer Anfangsbuchstabe
Namen, die aus mehr als einem Wort bestehen, werden zusammengeschrieben, wobei jedes neue Wort mit einem Gro"sbuchstaben eigeleitet wird.
Prozeduren sollen mit einem Verb beginnen (Bsp. writeString)

Folie: Versionsverwaltung

Was sollten wir haben?
- (Halb-)Automatische Versions und Verionsnummerverwaltung
- In Arbeit befindliche Dateien sperren
- Rückholung alter Versionen
- Kommentare für alte Versionen
- Mehrbenutzerfähig
Benutzung von RCS oder CVS