Para̲meter der Dokumentation in C♯ 

Die Aussprache des deutschen Wortes „Parameter“ lautet /paˈʀaːmetɐ/, man beachte die Betonung auf der zweiten  Silbe!

Die Aussprache des englischen Wortes “parameter ” lautet /pəˈræˌmɪtɚ/ oder kurz /pˈræˌmɪtɚ/.

Typerwartungen

Der Aufrufausdruck »global::System.Math.Floor( 2.7 )« besteht aus einem Rahmen »global::System.Math.Floor( … )« und einem an Stelle der Lücke »…« eingesetztem Argumentausdruck »2.7«.

Program.cs

public static class Program
{ public static void Main()
  { global::System.Console.WriteLine
    ( global::System.Math.Floor( 2.7 ) ); }}

Protokoll

2

Für diese Lücke »…« darf jedoch im allgemeinen nicht irgendein beliebiger  Wertausdruck eingesetzt werden. Das folgende Programm zeigt, daß ein Ausdruck vom Typ »string« beispielsweise zu einer Fehlermeldung führt.

Program.cs

public static class Program
{ public static void Main()
  { global::System.Console.WriteLine
    ( global::System.Math.Floor( "2.7" ) ); }}

Konsole (übersetzt und überarbeitet)

Program.cs(4,34): Fehler CS1503: Argument 1: kann nicht von 'string' nach 'double' gewandelt werden

Die Fehlermeldung drückt aus, daß ein Ausdruck vom Typ »double« erwartet wurde, während tatsächlich ein Ausdruck vom Typ »string« gefunden wurde.

Parametertypen und Parameternamen

In der Dokumentation einer Methode findet man in den Klammern hinter dem Methodennamen einen Parametertyp  und einen Parameternamen.

Dokumentation einer Methode mit einem Para̲metertyp und einem Parameternamen (verändert und übersetzt)

Namensraum »global::System«

Klasse »Math«

public static double Floor( double d )

Rundet einen Wert des Typs »double« ab.

In der obenstehenden Dokumentation ist »double« der Parametertyp und »d« der Parametername.

Der Parametername, sowie die Angaben »public« und »static« werden manchmal zur Verkürzung der Dokumentation (besonders in Übersichten ohne Details) weggelassen.

Parameter

Ein Parameter ist eine vorgestellte Sache, die durch die folgenden Eigenschaften bestimmt ist:

• Die Methode, zu welcher der Parameter gehört und
• den Namen des Parameters (den Parameternamen).

Darüber hinaus hat ein Parameter noch folgende Eigenschaften:

• Einen Typ (den Parametertyp).

Parametereigenschaften in der Dokumentation

Wenn eine Methode einen Parameter hat, kann man ihrer Dokumentation jene Eigenschaften ihres Parameters entnehmen:

• Die Methode, zu welcher der Parameter gehört ist die Methode, die in jener Dokumentation dokumentiert wird.
• Der Name des Parameters  findet sich in der Proklamation jener Methode in den runden Klammern am Ende. (Nur bei den ausführlichen Dokumentationen, nicht in Übersichtslisten.)
• Der Typ des Parameters  findet sich in der Proklamation jener Methode in den runden Klammern vor dem Namen.

Die Angaben zu einem Parameter in den Klammern nennen wir auch eine Parameterproklamation.

Parametereigenschaften am Beispiel von »global::System.Math.Floor«

Der oben gezeigten Dokumentation kann man beispielsweise entnehmen, daß die Methode »global::System.Math.Floor« einen Parameter mit den folgenden Eigenschaften hat:

• Die Methode des Parameters ist »global::System.Math.Floor«.
• Der Name des Parameters lautet »a«.
• Der Typ des Parameters ist »double«.

Parameterinkarnationen

Bei einem Aufruf einer Methode, die einen Parameter hat, wird eine Inkarnation jenes Parameters angelegt.

Eine Parameterinkarnation  ist eine vorgestellte Sache, die alle Eigenschaften ihres Parameters übernimmt und zusätzlich noch einen Wert  hat, den wir auch Parameterinkarnationswert  oder – kürzer und nicht ganz korrekt – Parameterwert  nennen.

Beim Aufruf »global::System.Math.Floor( 2.0 + 4.0 )« wird beispielsweise eine Inkarnation des Parameters »a« angelegt, die den Wert »6.0« hat.

Beim Aufruf »global::System.Math.Floor( 3.0 + 8.0 )« wird wieder eine andere Inkarnation des Parameters »a« angelegt, diesmal mit dem Wert »11.0«.

Argumenttypen

Wir nennen den Typ des Argumentausdrucks eines Aufrufs auch den Argumenttyp  jenes Aufrufs.

Es wird erwartet, daß der Argumenttyp  gleich dem Parametertyp  ist.

Dies ist die Erklärung dafür, daß der am Anfang dieser Lektion gezeigte Aufruf der Methode »global::System.Math.Floor« mit dem Argumentausdruck »"2.7"« nicht möglich war. Diese Methode hat einen double-Parameter, aber der Ausdruck »"2.7"« hat den Typ »string«.

Später werden wir noch lernen, daß in einigen Fällen auch noch andere Argumenttypen zulässig sind, die nicht mit dem Parametertyp übereinstimmen. Bis dahin ist es das Sicherste zunächst darauf zu achten, daß der Argumenttyp immer dem Parametertyp gleicht.

Para̲meterproklamationen und Argumentausdrücke

Para̲meterproklamationen  und Argumentausdrücke  werden manchmal miteinander verwechselt : Para̲meterproklamationen  finden sich in der Dokumentation  als Beschreibung einer Lücke, sie drücken das Fehlen  eines bestimmten Wertes aus, die Erwartung  eines Ausdrucks beim Aufruf im Quelltext. Argumentausdrücke  finden sich im Quelltext innerhalb mancher Ausdrücke  und geben den zur Ermittlung des Para̲meterwerts zu nutzenden Ausdruck an, beispielsweise als ein Numerale oder als eine Summe. Da Para̲meterbeschreibungen das Fehlen  eines Wertes ausdrücken und Argumentausdrücken einen Wert  ausdrücken, sind Argumentausdrücke  gewissermaßen das Gegenstück zu Para̲meterbeschreibungen. (Der Parameter ist der Parkplatz und das Argument ist das Auto.)

Das Schreiben von Aufrufen

Das folgende Beispielprogramm zeigt einen der Dokumentation der Methode »global::System.Math.Floor« entsprechenden Aufruf jener Methode mit einem Argumentausdruck vom Typ »double«.

Program.cs

public static class Program
{ public static void Main()
  { global::System.Console.WriteLine
    ( global::System.Math.Floor( 2.7 )); }}

Protokoll

3

Hier zeigen wir nun die Proklamation  der Methode »global::System.Math.Floor« und zum Vergleich einen Aufruf  jener Methode.

Proklamation

public static double Floor( double d )

Aufruf

global::System.Math.Floor( 2.7 )

Man beachte den Unterschied zwischen der Proklamation und dem Aufruf! Das einzige Wort, das oben in beidem vorkommt, ist »Floor«. Trotzdem werden beide von Anfängern oft verwechselt, und nach dem Lesen von Dokumentation werden von Anfängern oft Proklamationen an Stelle von Aufrufen in Programme hineingeschrieben.

Wir schreiben keine Proklamationen  in Programme hinein, sondern nur Aufrufe ! Die Proklamationen der Dokumentation sind lediglich zum Lesen  gedacht.

Leere Para̲meterlisten

Wenn die Klammern hinter dem Methodennamen in der Dokumentation leer  sind, dann hat die dokumentierte Methode keinen Para̲meter, und muß entsprechend auch mit leeren Klammern  (also ohne Argument ) aufgerufen werden.

Dokumentation von »global::System.AppDomain.GetCurrentThreadId« (gekürzt und vereinfacht)

Namensraum global::System 
Klasse AppDomain 
Methode
veraltet
Syntax:
public static int GetCurrentThreadId()
Ergibt die Kennung des laufenden Programmes.

Wer aufruft, ist verantwortlich

Unter einem Benutzer  einer Methode verstehen wir einen Programmierer, der einen Aufruf jener Methode schreibt.

Der Benutzer  einer Methode ist dafür verantwortlich, eventuelle Einschränkungen, die in der Dokumentation der Methode festgelegt werden, zu beachten. Steht in der Prosa beispielsweise, daß eine Methode nicht mit dem Argumentwert »0« aufgerufen werden darf, dann ein Benutzer nicht erwarten, daß die Methode sich wie erwartet verhält, wenn er sie doch mit dem Argumentwert »0« aufruft.

Die Dokumentation einer Methode ist wie ein Vertragsangebot zu verstehen. Durch die Benutzung der Methode nimmt der Benutzer das Vertragsangebot an, und muß sich dann auch daran halten.

Groß geschriebene Typnamen in der Originaldokumentation

In der Originaldokumentation werden Typen manchmal auch durch den eigentlichen Namen am Ende ihrer nicht-einfachen  Schreibweise angegeben.

Die Typaliasse in C♯

einfache  nicht-einfache           Bezeichnung in
Schreib-  Schreibweise             der Dokumentation
weise
int       global::System.Int32     Int32
double    global::System.Double    Double
decimal   global::System.Decimal   Decimal
string    global::System.String    String

Wir hatten oben zur Vereinfachung die einfache Schreibweise verwendet, aber ab jetzt werden wir auch manchmal die Schreibweise aus der Originaldokumentation übernehmen.

Weitere Beispiele für Methodendokumentationen

Hier zeigen wir die Dokumentation einiger Methoden, von denen einige schon verwendet wurden.

Dokumentation einer Methode mit einem Para̲metertyp und einem Parameternamen (verändert und übersetzt)

Namensraum »global::System«

Klasse »Decimal«

public static decimal Negate( decimal d )

Ergibt einen Wert des Typs »decimal«, welcher den Betrag des Wertes des Arguments, aber ein anderes Vorzeichen hat.

Dokumentation einer Methode mit einem Para̲metertyp und einem Parameternamen (verändert und übersetzt)

Namensraum »global::System«

Klasse »Math«

public static double Sin( double d )

Ergibt den Sinus des Argumentwerts.

Dokumentation einer Methode mit einem Para̲metertyp und einem Parameternamen (verändert und übersetzt)

Namensraum »global::System«

Klasse »Math«

public static double Cos( double d )

Ergibt den Kosinus des Argumentwerts.

Dokumentation einer Methode mit einem Para̲metertyp und einem Parameternamen (verändert und übersetzt)

Namensraum »global::System«

Klasse »Math«

public static double Sqrt( double d )

Ergibt die Quadratwurzel des Argumentwerts.

Dokumentation einer Methode mit einem Para̲metertyp und einem Parameternamen (verändert und übersetzt)

Namensraum »global::System«

Klasse »Double«

public static double Parse( string s )

Ergibt den Zahlenwert der als Argumentwert übergebenen Zeichenfolge.

Übungsfragen

?   Verständnis von Fachbegriffen

Zu einer (hypothetischen) Methode »f« wird erklärt: „Die Methode »f« ergibt den Wert ihres Arguments.“. Welchen Wert hat dann »f( 3 )«?

Zu einer (hypothetischen) Methode »m« wird erklärt: „Die Methode »m« ergibt stets den Wert 4.“. Welchen Wert hat dann »m( 3 )«?

?   Dokumentation lesen

In einer Proklamation einer Methode »f« findet sich »int f( double x )« – was bedeutet darin das »int« und was das »double«?

?   Dokumentation lesen (1)

In einer Proklamation einer Methode »f« findet sich »int f( double x )« – ist »x« darin ein Parametername oder ein Argumentausdruck?

?   Quelltext lesen

In einem Programm findet sich der Ausdruck »global::System.Decimal.Negate( 3m + 1m )« – ist »3m + 1m« darin ein Parametername oder ein Argumentausdruck?

?   Dokumentation und Quelltext lesen

Angenommen, man findet in der Dokumentation zwei Proklamationen: »string f( int i )« und »int g()«, welche der folgenden Aufrufe sind dann erlaubt?

• »f( g() )«
• »g( f() )«

?   Dokumentation lesen (2)

Dokumentation einer Methode mit einem Para̲metertyp und einem Parameternamen (verändert und übersetzt)

Namensraum »global::System«

Klasse »Math«

public static double Round( double a )

Ergibt den gerundeten Wert des Argumentwerts.

Fragen zum Verständnis der obigen Dokumentation

• Welchen Namen hat der Para̲meter  der Methode?
• Welchen Datentyp  hat der Para̲meter der Methode?
• Welchen Datentyp hat ein Aufruf  der Methode?
• Welchen eigentlichen Namen  hat die dokumentierte Methode? *

?   Reihenfolge von Rechenschritten

In welcher Reihenfolge werden die beiden Methoden bei der Auswertung des folgenden Ausdrucks aktiviert?

Ausdruck

global::System.Math.Cos( global::System.Math.Exp( 2 ))

?   Quelltext beurteilen

Ist das folgende Programm korrekt? Begründen Sie Ihre Antwort!

Program.cs

public static class Program
{ public static void Main()
  { global::System.Console.WriteLine
    ( public static double Floor( double d ); }}

?   Ausdrücke lesen *

Können Sie – ohne ein C# -Programm zu starten – den ungefähren Wert des Ausdrucks »global::System.Math.Sqrt( global::System.Math.Sqrt( 16.0 ))« vorhersagen?

?   Datentypen ermitteln *

Welchen Datentyp hat der Ausdruck »global::System.Math.Sqrt( global::System.Math.Sqrt( 16.0 ))«?

Welchen Datentyp hat der Ausdruck »global::System.Double.Parse( "123" )«?

?   Bedeutung von Ausdrücken **

Ist »global::System.Math.Abs( 2 )« eine Methode?

?   Quelltext beurteilen **

erste Zeile (aus einer Dokumentation)

public static double Floor( double d )

zweite Zeile (aus einem Quelltext)

global::System.Math.Floor( 2.7 )

Nennen Sie Unterschiede zwischen den voranstehenden beiden Zeilen, indem Sie die Lücken „____________________“ in den folgenden beiden Sätzen ausfüllen.

In der ersten Zeile steht vor »floor« ____________________, in der zweiten Zeile steht vor »floor« ____________________.

In der ersten Zeile steht in den Klammern ____________________, in der zweiten Zeile steht in den Klammern ____________________.

Übungsaufgaben

/   Aufruf schreiben

msdn.microsoft.com/library/system.math.abs (vereinfacht und übersetzt)

Namensraum »global::System«

Klasse »Math«

public static double Abs(double)

Ergibt den Betrag des Argumentwertes.

Diese Übungsaufgabe soll das selbständige Schreiben von Aufrufen von Methoden mit einem Para̲meter an Hand der Dokumentation üben.

Schreiben Sie ein Programm, welches das Ergebnis eines Aufrufs der Methode »Abs« mit dem Argumentausdruck »5.0« ausgibt. (Die Ausgabe sollte »5.0« lauten.)

Denken Sie daran, nichts  aus der Dokumentation in das Programm zu kopieren!

Reserveaufgaben

/   Aufruf schreiben (1)

Hinweis für den Dozenten  ► Diese Übungsaufgabe sollte erst nach der Nachbesprechung der vorherigen Übungsaufgabe in Angriff genommen werden.

msdn.microsoft.com/en-us/library/c2eabd70(v=vs.110).aspx (vereinfacht und übersetzt)

Namensraum »global::System«

Klasse »Math«

public static double Truncate( double d )

Ergibt den ganzzahligen Anteil des Argumentwertes.

Schreiben Sie ein Programm, welches einen Aufruf der Methode »Truncate« aus der Klasse »global::System.Math« enthält.

/   Aufruf schreiben (2)

Hinweis für den Dozenten  ► Diese Übungsaufgabe sollte erst nach der Nachbesprechung der vorherigen Übungsaufgabe in Angriff genommen werden.

msdn.microsoft.com/library/system.environment.GetEnvironmentVariable (vereinfacht und übersetzt)

Namensraum »global::System«

Klasse »Environment«

public static string GetEnvironmentVariable( string )

Ergibt den Wert einer Umgebungsvariablen mit dem angegebenen Namen (wie beispielsweise »PATH«).

Schreiben Sie ein Programm, welches einen Aufruf der Methode »GetEnvironmentVariable« aus der Klasse »global::System.Environment« enthält.

Übungsaufgaben

/   Mathematische Aufrufe schreiben

Hinweis für den Dozenten  ► Diese Aufgabe sollte nicht vor der Nachbesprechung der vorigen Übungsaufgabe behandelt werden.

Schreiben Sie möglichst kurze Ausdrücke, die den folgenden sprachlichen Bezeichnungen entsprechen, ohne dabei den Wert des Ausdrucks schon selber im Kopf auszurechnen! Die Werte der Ausdrücke sollten den mathematischen Werten der vorgegebenen Texte möglichst nahe kommen. (Passende Methoden können in der Klasse »Math« aus dem Namensraum »global::System« gefunden werden.)

• Der Kosinus von Null (Die Ausgabe sollte »1.0« lauten.)
• Die Wurzel aus zwölf Prozent von Vierundsiebzig (Die Ausgabe sollte zirka »2.97993288515027« lauten.)

Zusatzfragen *

?   Ausdrücke lesen *

Die folgenden Fragen sollen durch Lesen der Dokumentation beantwortet werden, nicht durch Ausprobieren (Starten von Programmen).

Welche Werte kann der Ausdruck »global::System.Math.Floor( global::Microsoft.JScript.MathObject.random() * 3 )« haben?

Welche Werte kann der Ausdruck »global::System.Math.Ceiling( global::Microsoft.JScript.MathObject.random() * 3 )« haben?

Welche Werte kann der Ausdruck »global::System.Math.Round( global::Microsoft.JScript.MathObject.random() * 3 )« haben?