diff --git a/Doc/Sd1/gettingStarted.xml b/Doc/Sd1/gettingStarted.xml
index ce1f4af3e115aa571e5e761ddb68a55c7ae9dafd..0f814ea66f50f02edcc281d1c9c05d0182a6e7f7 100644
--- a/Doc/Sd1/gettingStarted.xml
+++ b/Doc/Sd1/gettingStarted.xml
@@ -722,8 +722,7 @@ public class HelloWorld <co
xml:id="sd1_fig_listing_structureClassDefinition-3">
<para><code language="java">public static void main(String[]
args)</code> is a so called <link
- linkend="sd1SectStaticMembers">class method</link>
- definition.</para>
+ linkend="sd1SectClassMembers">class method</link> definition.</para>
<para>For the time being we present a rule of thumb: Every <xref
linkend="glo_Java"/> program to become executable requires at least
diff --git a/Doc/Sd1/languageFundamentals.xml b/Doc/Sd1/languageFundamentals.xml
index fac6e176b34d5491f3e491e9746aa2d9a91652e5..65fc26aa16102f14f70d503d94517a66b97f1628 100644
--- a/Doc/Sd1/languageFundamentals.xml
+++ b/Doc/Sd1/languageFundamentals.xml
@@ -471,52 +471,36 @@ int c;</programlisting>
</informaltable>
</figure>
- <figure xml:id="sd1_fig_varNameConventions">
- <title>Variable naming conventions</title>
+ <figure xml:id="sd1_fig_variableNameIsIdentifier">
+ <title>Identifier</title>
<itemizedlist>
<listitem>
- <para>Start with a small letter like <code
- language="java">africa</code> rather than <code
- language="java">Africa</code>.</para>
- </listitem>
-
- <listitem>
- <informaltable border="0">
- <colgroup width="42%"/>
-
- <colgroup width="58%"/>
-
- <tr>
- <td valign="top">Use <quote>camel case</quote> e.g. <code
- language="java">myFirstCode</code>.</td>
-
- <td valign="top"><mediaobject>
- <imageobject>
- <imagedata fileref="Ref/LangFundament/camelCase.svg"/>
- </imageobject>
- </mediaobject></td>
- </tr>
- </informaltable>
- </listitem>
-
- <listitem>
- <para>Do not start with <code language="java">_</code> or <code
- language="java">$</code>.</para>
+ <para><link
+ xlink:href="https://docs.oracle.com/javase/specs/jls/se12/html/jls-3.html#jls-3.8">Identifier</link>
+ in <xref linkend="glo_Java"/> relate to:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Variable names.</para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="sd1_fig_classes">Class</link> names</para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="sd1_sect_methods">Method</link> names, e.g.
+ <methodname>public static void
+ main(String[args])</methodname>.</para>
+ </listitem>
+ </itemizedlist>
</listitem>
</itemizedlist>
</figure>
- <figure xml:id="sd1_fig_varFinal">
- <title>Constants</title>
-
- <programlisting language="java">final double pi = 3.1415926;
-...
-pi = 1.0; // Compile time error: Constant cannot be modified</programlisting>
- </figure>
-
<figure xml:id="sd1_fig_legalVariableName">
- <title>Variable names (identifier)</title>
+ <title>Identifier names</title>
<informaltable border="1">
<colgroup width="73%"/>
@@ -618,14 +602,59 @@ class finally long strictfp volatile
const float native super while</programlisting>
</figure>
+ <figure xml:id="sd1_fig_varNameConventions">
+ <title>Variable naming conventions</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Start with a small letter like <code
+ language="java">africa</code> rather than <code
+ language="java">Africa</code>.</para>
+ </listitem>
+
+ <listitem>
+ <informaltable border="0">
+ <colgroup width="42%"/>
+
+ <colgroup width="58%"/>
+
+ <tr>
+ <td valign="top">Use <quote>camel case</quote> e.g. <code
+ language="java">myFirstCode</code>.</td>
+
+ <td valign="top"><mediaobject>
+ <imageobject>
+ <imagedata fileref="Ref/LangFundament/camelCase.svg"/>
+ </imageobject>
+ </mediaobject></td>
+ </tr>
+ </informaltable>
+ </listitem>
+
+ <listitem>
+ <para>Do not start with <code language="java">_</code> or <code
+ language="java">$</code>.</para>
+ </listitem>
+ </itemizedlist>
+ </figure>
+
+ <figure xml:id="sd1_fig_varFinal">
+ <title>Constants</title>
+
+ <programlisting language="java">final double pi = 3.1415926;
+...
+pi = 1.0; // Compile time error: Constant cannot be modified</programlisting>
+ </figure>
+
<figure xml:id="sd1_fig_varCaseSensitive">
<title>Case sensitivity</title>
<para>Variable names are case sensitive:</para>
- <programlisting language="java">int count = 32;
-int Count = 44;
-System.out.println(count + ":" + Count);</programlisting>
+ <programlisting language="none">int <emphasis role="red">c</emphasis>ount = 32;
+int <emphasis role="red">C</emphasis>ount = 44;
+System.out.println(<emphasis role="red">c</emphasis>ount + ":" + <emphasis
+ role="red">C</emphasis>ount);</programlisting>
<para>Resulting output:</para>
@@ -638,8 +667,10 @@ System.out.println(count + ":" + Count);</programlisting>
<qandadiv>
<qandaentry>
<question>
- <para>Which of the following names are legal variable names?
- Complete the following table and explain your decision with
+ <para>Which of the following names are legal variable names? If
+ so, would you actually use them in your code?</para>
+
+ <para>Complete the following table and explain your decision with
respect to the <quote>Language Fundamentals</quote> /
<quote>variables</quote> section of <xref
linkend="bib_Kurniawan"/> .</para>
@@ -654,7 +685,7 @@ System.out.println(count + ":" + Count);</programlisting>
<tr>
<th>Identifier</th>
- <th>is legal? (yes / no)</th>
+ <th>Legal? (yes / no)</th>
<th>Explanation / remark</th>
</tr>
@@ -794,7 +825,7 @@ System.out.println(count + ":" + Count);</programlisting>
<tr>
<th>Identifier</th>
- <th>is legal? (yes / no)</th>
+ <th>Legal? (yes / no)</th>
<th>Explanation / remark</th>
</tr>
@@ -837,8 +868,9 @@ System.out.println(count + ":" + Count);</programlisting>
<td>yes</td>
- <td>Best practices: Discouraged variable name, non-constant
- variables should start with lowercase letters.</td>
+ <td>Discouraged by »Best practices« if non-constant (<code
+ language="java">final</code>): Non-constant variables should
+ start with lowercase letters.</td>
</tr>
<tr>
@@ -854,9 +886,10 @@ System.out.println(count + ":" + Count);</programlisting>
<td>yes</td>
- <td><code language="java">println</code> is a method of <code
- language="java">System.out.println(...)</code> but is no <xref
- linkend="glo_Java"/> keyword.</td>
+ <td><code language="java"><methodname
+ xlink:href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/PrintStream.html#println(java.lang.String)">println</methodname></code>
+ is a method's name but is no <xref linkend="glo_Java"/>
+ keyword.</td>
</tr>
<tr>
@@ -864,8 +897,7 @@ System.out.println(count + ":" + Count);</programlisting>
<td>yes</td>
- <td>Best practices: Discouraged variable name, non-constant
- variables should start with lowercase letters.</td>
+ <td>See »ABC« above.</td>
</tr>
<tr>
@@ -873,9 +905,7 @@ System.out.println(count + ":" + Count);</programlisting>
<td>yes</td>
- <td>Best practices: Legal but discouraged variable name:
- Non-constant variables should start with lowercase
- letters.</td>
+ <td>See »ABC« above.</td>
</tr>
<tr>
@@ -891,7 +921,8 @@ System.out.println(count + ":" + Count);</programlisting>
<td>yes</td>
- <td>Best practices: Should be reserved for system code.</td>
+ <td>Discouraged by »Best practices«: Identifier starting with
+ »_« should be reserved for system code.</td>
</tr>
<tr>
@@ -908,8 +939,8 @@ System.out.println(count + ":" + Count);</programlisting>
<td>yes</td>
- <td>Best practices: Using the <quote>$</quote> sign should be
- reserved for system code.</td>
+ <td>Discouraged by »Best practices«: Identifier starting with
+ »$« should be reserved for system code.</td>
</tr>
</informaltable>
</answer>
diff --git a/Doc/Sd1/objectsClasses.xml b/Doc/Sd1/objectsClasses.xml
index 04fdbcac15d92e1f5a67b6d08637cec3e5cc0e1f..7ca3b7eaafe7e9ee376e692190dbd3a3e760fc5e 100644
--- a/Doc/Sd1/objectsClasses.xml
+++ b/Doc/Sd1/objectsClasses.xml
@@ -1367,10 +1367,10 @@ public class SetterAccess {
</qandaset>
</section>
- <section xml:id="sd1_sect_methodSignature">
+ <section xml:id="sd1_typeSignature_slide">
<title>Signatures</title>
- <figure xml:id="sd1_fig_typeSignatureDef">
+ <figure xml:id="sd1_typeSignatureDef_slide">
<title>Defining type signatures</title>
<programlisting language="java">boolean <co
@@ -1388,18 +1388,23 @@ public class SetterAccess {
<callout arearefs="sd1_fig_typeSignatureDef-2-co"
xml:id="sd1_fig_typeSignatureDef-2">
- <para>Number of arguments among with their respective types and
+ <para>Arguments among with their respective types and
order:</para>
- <para>Two argument types: String followed by <code
- language="java">int</code>. Consider:</para>
+ <orderedlist>
+ <listitem>
+ <para>Type <code language="java">String</code></para>
+ </listitem>
- <programlisting language="java">boolean startsWith​(int toffset, String prefix) </programlisting>
+ <listitem>
+ <para>Type <code language="java">int</code></para>
+ </listitem>
+ </orderedlist>
</callout>
</calloutlist>
</figure>
- <figure xml:id="sd1_fig_typeSignature">
+ <figure xml:id="sd1_fig_typeSignatureSamples">
<title>Type signature examples</title>
<informaltable border="1">
@@ -1459,7 +1464,7 @@ public class SetterAccess {
</informaltable>
</figure>
- <figure xml:id="sd1_fig_typeSignatureDetail">
+ <figure xml:id="sd1_methodSignatureDef_slide">
<title>Defining method signatures</title>
<programlisting language="java">boolean <link
@@ -1542,6 +1547,127 @@ public class SetterAccess {
</tr>
</informaltable>
</figure>
+
+ <qandaset defaultlabel="qanda"
+ xml:id="sd1_oc_methodSignatureVariants_qanda">
+ <title>Method signature variants</title>
+
+ <qandadiv>
+ <qandaentry>
+ <question>
+ <para>Consider the following method definitions:</para>
+
+ <orderedlist>
+ <listitem>
+ <programlisting language="java">boolean startsWith​(String value, int position) </programlisting>
+ </listitem>
+
+ <listitem>
+ <programlisting language="java">boolean startsWith​(int toffset, String prefix) </programlisting>
+ </listitem>
+
+ <listitem>
+ <programlisting language="java">boolean startswith​(String prefix, int toffset) </programlisting>
+ </listitem>
+ </orderedlist>
+
+ <para>Which of these have the same method signature as <xref
+ linkend="sd1_methodSignatureDef_slide"/>?</para>
+ </question>
+
+ <answer>
+ <para>We start by the original method:</para>
+
+ <programlisting language="java">boolean <link
+ xlink:href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html#startsWith(java.lang.String,int)">startsWith</link>​(String prefix, int toffset) </programlisting>
+
+ <para>Its signature may be represented by:</para>
+
+ <para> {"startsWith", String, int​} </para>
+
+ <para>This describes the method's name and all its argument
+ types among with their respective order. We now cover the
+ different definitions:</para>
+
+ <informaltable border="1">
+ <colgroup width="7%"/>
+
+ <colgroup width="53%"/>
+
+ <colgroup width="40%"/>
+
+ <tr>
+ <th/>
+
+ <th>Method</th>
+
+ <th>Method signature</th>
+
+ <th/>
+ </tr>
+
+ <tr>
+ <td valign="top">Original</td>
+
+ <td valign="top"><programlisting language="java">boolean startsWith​(String prefix, int toffset)</programlisting></td>
+
+ <td valign="top">("startsWith", String, int​)</td>
+ </tr>
+
+ <tr>
+ <td rowspan="2" valign="top">1</td>
+
+ <td valign="top"><programlisting language="java">boolean startsWith​(String value, int position)</programlisting></td>
+
+ <td valign="top">("startsWith", String, int​)</td>
+ </tr>
+
+ <tr>
+ <td colspan="2">Same method signature: Only the argument
+ types matter irrespective of formal parameter names
+ <varname>value</varname> and
+ <varname>position</varname>.</td>
+ </tr>
+
+ <tr>
+ <td rowspan="2" valign="top">2</td>
+
+ <td valign="top"><programlisting language="java">boolean startsWith​(String prefix, int toffset)</programlisting></td>
+
+ <td valign="top">("startsWith", String, int​)</td>
+ </tr>
+
+ <tr>
+ <td colspan="2">Different method signature: The order of
+ types being reversed here matters.</td>
+ </tr>
+
+ <tr>
+ <td rowspan="2" valign="top">3</td>
+
+ <td valign="top"><programlisting language="java">boolean starts<emphasis
+ role="red">w</emphasis>ith​(int toffset, String prefix)</programlisting></td>
+
+ <td valign="top">("starts<emphasis
+ role="red">w</emphasis>ith", int​, String)</td>
+ </tr>
+
+ <tr>
+ <td colspan="2">Different method signature: For <xref
+ linkend="glo_Java"/> <link
+ xlink:href="https://docs.oracle.com/javase/specs/jls/se12/html/jls-3.html#jls-3.8">identifiers</link>
+ being case sensitive method names
+ <methodname>starts<emphasis
+ role="red">W</emphasis>ith</methodname> and
+ <methodname>starts<emphasis role="red">w</emphasis>ith
+ differ</methodname>. So do the resulting method
+ signatures.</td>
+ </tr>
+ </informaltable>
+ </answer>
+ </qandaentry>
+ </qandadiv>
+ </qandaset>
</section>
<section xml:id="sd1_sect_methodOverloading">
@@ -3621,8 +3747,8 @@ seconds = 23</screen></td>
</section>
</section>
- <section xml:id="sd1SectStaticMembers">
- <title>Static Members</title>
+ <section xml:id="sd1SectClassMembers">
+ <title>Class members and methods</title>
<figure xml:id="sd1_fig_staticMemberObjective">
<title>Club membership objectives</title>
diff --git a/Doc/Sd1/statements.xml b/Doc/Sd1/statements.xml
index 7933cf7241aea5cf7f1de0d8f1bd506e27297c60..f9a99197be6431adb273a13c616b3bde34c7807f 100644
--- a/Doc/Sd1/statements.xml
+++ b/Doc/Sd1/statements.xml
@@ -2929,11 +2929,11 @@ for (int row = 0; row < numberOfRows; row++) {
task namely indenting lines by a given amount of spaces.</para>
<para>So far we have not yet introduced methods. In anticipation
- of <link linkend="sd1SectStaticMembers">upcoming lessons</link>
- we provide an alternate solution by introducing a method
- <methodname>printIndented(...)</methodname> which prints a given
+ of <link linkend="sd1SectClassMembers">class methods</link> we
+ provide an alternate solution introducing a method
+ <methodname>printIndented(...)</methodname> printing a given
string a configurable number of times being indented by a given
- number of whitespace characters using <package
+ number of whitespace characters. This method uses <package
xlink:href="https://docs.oracle.com/javase/10/docs/api/java/lang/System.html">System</package>.<parameter
xlink:href="https://docs.oracle.com/javase/10/docs/api/java/lang/System.html#out">out</parameter>.<methodname
xlink:href="https://docs.oracle.com/javase/10/docs/api/java/io/PrintStream.html#format(java.lang.String,java.lang.Object...)">format(...)</methodname>