tipps.tex 9.05 KB
Newer Older
denis.lohner's avatar
denis.lohner committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
\documentclass{article}

\usepackage[utf8]{inputenc} % utf8 file encoding
\usepackage[T1]{fontenc} % powerful pdf output encoding

\usepackage[color]{PPaushang}
\usepackage{helvet}
\usepackage{csquotes}

\usepackage[german]{babel}

\setlength{\parskip}{12pt}

\title{Praxis der Software-Entwicklung \\
  \Large{Tipps und Tricks}}
\author{%
  \normalsize{Lehrstuhl Programmierparadigmen}\\
  \normalsize{Karlsruher Institut f\"ur Technologie (KIT)}}
\date{\normalsize{Stand: \today}}

\begin{document}
\maketitle

Manche Tipps und Tricks geben wiederholen wir häufig.
Dies ist eine Sammlung, um nichts zu vergessen
und weniger Fehler beim Erklären zu machen.

\section{Technisches}
\subsection{Versionskontrollsystem}

Wir empfehlen Subversion oder Git,
weil wir als Betreuer damit Erfahrung haben.

Git-Tipps:

\begin{itemize}
  \item \href{http://try.github.io}{Interactive Git Tutorial}: für Anfänger.
  \item \href{http://gitref.org/}{Git Reference}: relativ kompakte Anleitung.
  \item \href{http://git-scm.com/}{Offizielle Git Projektseite}
  \item \href{http://eagain.net/articles/git-for-computer-scientists/}
    {Git for Computer Scientists}:
    \enquote{Quick introduction to git internals for people who are not scared by words like Directed Acyclic Graph.}
  \item Vermeide den Parameter \texttt{--force} bzw. \texttt{-f}.
    Häufig schiebst du damit Probleme nur deinen Teamkollegen zu.
\end{itemize}

\subsection{Dokumentenformat}

Wir empfehlen \LaTeX,
weil es sich gut mit Versionskontrollsystemen vereinbaren lässt
und man hier schon für die Bachelorarbeit üben kann.
Office o.ä. ist aber auch möglich.

\subsection{UML Diagramme}

\begin{itemize}
  \item \href{http://umbrello.kde.org/}{Umbrella} um einfach nur Diagramme zu zeichnen
  \item \href{http://argouml.tigris.org/}{ArgoUML} um auch Code zu generieren und beim Entwurf zu helfen
  \item \href{http://www-01.ibm.com/software/rational/uml/}{IBM Rational Software Architect} ist im ATIS Pool installiert.
\end{itemize}

Andreas Zwinkau's avatar
Andreas Zwinkau committed
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
\section{Kolloquium}

Ein paar Hinweise für die Kollquien bzw. für Präsentation allgemein.

\begin{itemize}
  \item Alleine Üben!
    Daheim vor dem Spiegel üben.
    Einen Vortrag nur alleine, aber im Stehen und laut sprechend, vorzutragen
    ist meist schon lehrreich im Vergleich zu stillem Folienbasteln.
  \item Vor dem eigenen Team üben und konstruktiv gegenseitig kritisieren.
    Oft sehen die Kollegen Ticks, die man selbst nicht wahrnimmt.
    Beispielsweise häufige Ähs, häufiges Wegschauen vom Publikum,
    verschränkte Arme, Nuscheln, nervöses herumlaufen, etc.
  \item 10 Minuten sind nicht lange,
    aber man kann viel Information darin unterbringen.
  \item Prof. Snelting achtet sehr auf die Zeit.
    10 Minuten sind nicht 12 Minuten und auch nicht 7 Minuten.
  \item Daumenregel: 2 Minuten pro Folie, also 5 Folien.
    Ein Folie umfasst dabei möglicherweise Animationen / Overlays.
  \item Die Folien dem Betreuer zur Durchsicht geben.
  \item Auf die interessanten Punkte konzentrieren
    und sich nicht in den Details verlieren.
    Trotzdem sollte natürlich der Inhalt möglichst vollständig sein.
Andreas Zwinkau's avatar
Andreas Zwinkau committed
85
86
  \item Keine Agenda-/Inhaltsverzeichnis-/Gliederungsfolie.
    Ist nicht mehr zeitgemäß und langweilt nur.
Andreas Zwinkau's avatar
Andreas Zwinkau committed
87
88
\end{itemize}

denis.lohner's avatar
denis.lohner committed
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
\section{Organisatorisches}

\begin{itemize}
  \item Meldet euch so früh wie möglich im \href{https://studium.kit.edu}{Studierendenportal} für PSE (Pr.Nr. 529) und TSE (Pr.Nr. 455) an.
  \item Mails an den Betreuer sollten vom Phasenverantwortlichen kommen.
\end{itemize}

\section{Pflichtenheft}

Das fertige (Software-)Produkt wird am Ende der gesamten Entwicklung am Pflichtenheft gemessen (Stichwort Endabnahme).
Stellt der Auftraggeber zu große Unterschiede fest, wird er nicht bezahlen.
D.h.\ schon das Pflichtenheft muss es dem Leser ermöglichen, eine exakte Vorstellung des fertigen Produkts zu bekommen.
Insbesondere müssen \emph{alle} Produktfunktionen und -daten genannt und hinreichend genau beschrieben werden,
(G)UI-Entwürfe sind Pflicht, Bedienelemente müssen erklärt sein (z.B. Menüführung), und der Leser muss durch das Pflichtenheft
wissen, wie er das fertige Produkt verwenden kann (Stichwort Testfallszenarien).

\begin{description}
  \item[Musskriterien]
    Mindestanforderungen, gehen aus Aufgabenstellung hervor.
    Möglichst klein halten.
  \item[Wunschkriterien]
    Von den Gruppen selbst definierte, zusätzliche Funktionalität.
  \item[Abgrenzungskriterien]
    Was unterstützt unser Produkt explizit \emph{nicht}.
\end{description}

Andreas Zwinkau's avatar
Andreas Zwinkau committed
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
Und noch einige generelle Anforderungen an das Pflichtenheft.

\begin{itemize}
  \item Wird jedes Kriterium durch mindestens einen Testfall geprüft?
    Zumindest intern (möglicherweise auch direkt im Pflichtenheft selbst)
    sollte für jedes Kriterium eine Liste an Testreferenzen
    und für jeden Test eine Liste an Kriteriumsreferenzen feststehen.
  \item Man stelle sich vor, das Pflichtenheft wird
    für Entwurf und Implementierung
    an ein anderes Team übergeben
    und das Ergebnis kommt zur Qualitätssicherung zurück.
    Wie zuversichtlich seid ihr,
    dass das Ergebnis euren Vorstellungen entspricht?
    Abweichungen von euren Vorstellung dürfen nur kritisiert werden,
    wenn dadurch Testfälle fehlschlagen.
  \item Das Pflichtenheft sollte auch von nicht technisch-versierten Menschen
    zu großen Teilen verstanden werden können.
    Am besten jemand fach-fremden zum Lesen geben
    und danach Verständnisfragen stellen.
\end{itemize}

\subsection{Struktur}

denis.lohner's avatar
denis.lohner committed
138
139
140
141
142
143
144
145
146
147
148
149
Beschreibung und Beispiele von Pflichtenheften
finden sich in der Vorlesung Softwaretechnik 1.
Die Struktur muss aber nicht exakt übernommen werden.
Sinnvolle Änderungen könnten sein:

\begin{itemize}
  \item Funktionale Anforderungen von Muss- und Wunschkriterien mischen und
    durch Layout, Stil, Marker, Icons entsprechend kennzeichnen.
  \item
    Ein Pflichtenheft darf mehr enthalten als nur einen Katalog an Kriterien.
    Das Endprodukt soll komplett erklärt werden,
    also könnte Hintergrundwissen aus anderen Quellen hilfreich sein.
Andreas Zwinkau's avatar
Andreas Zwinkau committed
150
151
152
153
154
155
  \item Reihenfolge der Kapitel verändern,
    so dass es flüssiger von vorne nach hinten gelesen werden kann.
  \item Testfallszenarien als Liste formatieren,
    so dass es als Checkliste für den Tester fungiert.
    Ein Punkte sollte dabei immer genau eine Aktion des Testers
    und die erwartet Reaktion des Programms sein.
denis.lohner's avatar
denis.lohner committed
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
\end{itemize}

\subsection{Technisches Schreiben}

Technisches Schreiben ist wichtig für alle Arten von technischen und wissenschaftlichen Dokumenten,
also auch API-Dokumentation, Bachelorarbeit und Pflichtenheft.
Es bedeutet vor allem eine präzise Ausdrucksweise
und widerspricht dabei einigen Regeln,
die man im Deutschunterricht gelernt hat.
Ein paar praktische Tipps:

\begin{itemize}
  \item Vermeide Adjektive.
    Oft (nicht immer) sind sie unnötig oder
    ein schlechter Ersatz für einen ungenauen Begriff.
  \item Definiere Begriffe klar und verwende keine Synonyme.
    Synonyme lassen offen, ob genau das gleiche gemeint ist
    oder nur etwas ähnliches.
Andreas Zwinkau's avatar
Andreas Zwinkau committed
174
175
  \item Abkürzungen sollten bei der ersten Verwendung (EV)
    ausgeschrieben werden. Nach der EV reicht dann die Kurzform.
denis.lohner's avatar
denis.lohner committed
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
  \item Versuche konkrete Zahlen und Namen anzugeben.
    Vermeide ungenaue Ausflüchte wie:
    meistens, viele, oft, möglichst, üblich, jemand, manche.
  \item Viele kurze Sätze sind einfacher zu verstehen als wenige lange Sätze.
  \item Beispiele machen das Endprodukt greifbarer.
  \item Illustrationen minimalistisch halten (z.B. IKEA Bauanleitung).
    Eine Information, ein Bild.
    Lieber mehrere ähnliche Bilder als ein komplexes Bild.
  \item Vermeide Wiederholung, stattdessen Referenzen benutzen.
    Wiederholungen haben oft subtile Unterschiede,
    was zu Unklarheit und Verwirrung führt.
    Bei Änderungen wird oft vergessen,
    dass Wiederholungen auch angepasst werden müssen.
  \item Versionskontrolle ergibt auch für technische Texte Sinn
    und nicht nur für Code.
\end{itemize}

Das Pflichtenheft ist das entscheidenste Dokument
zwischen Kunde und Entwickler am Ende eines Projekts.
Es darf \textbf{keinen Spielraum für Interpretationen} offen lassen.

\section{Entwurf}
Andreas Zwinkau's avatar
Andreas Zwinkau committed
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213

\begin{itemize}
  \item Detaillierte Beschreibung \emph{aller} Klassen
  \item Beschreibung von charakteristischen Abläufen (Testszenarien?)
    anhand von Sequenzdiagrammen
  \item Identifikation von Modulen
    die unabhängig voneinander implementiert und getestet werden können.
    Vorgriff auf den Implementierungsplan.
  \item Identifikation von Entwurfsmustern
    um Struktur gröber zu beschreiben.
  \item Vermeidung von Abhängigkeitszyklen.
    Design Patterns um Abhängigkeiten zu entfernen:
    Observer, Visitor, Strategy
  \item Vollständiges großformatiges Klassendiagramm im Anhang
\end{itemize}

Andreas Zwinkau's avatar
Andreas Zwinkau committed
214
215
216
217
218
219
220
\begin{itemize}
  \item \href{https://github.com/MatzeB/texdoclet}{TeXdoclet}
  um mit JavaDoc \LaTeX{} zu erzeugen.
  Das ermöglicht den automatischen Flow: ArgoUML $\rightarrow$ JavaDoc+TeXdoclet $\rightarrow$
  \LaTeX{} $\rightarrow$ Section \enquote{Klassenbeschreibung} im Entwurf.
\end{itemize}

denis.lohner's avatar
denis.lohner committed
221
222
\section{Implementierung}
\section{Qualitätssicherung}
Andreas Zwinkau's avatar
Andreas Zwinkau committed
223
\section{Abschlusspräsentation}
denis.lohner's avatar
denis.lohner committed
224
225

\end{document}