Hints regarding project quality

Doc/Sd1/appendix.xml

@@ -178,22 +178,133 @@
 
         <listitem>
           <para>Your team is expected to supply a Maven project based on the
-          MI Maven archetype quickstart.</para>
+          MI <quote>Maven archetype quickstart</quote> available from <uri
+          xlink:href="https://maven.mi.hdm-stuttgart.de/archetype-catalog.xml">https://maven.mi.hdm-stuttgart.de</uri>.</para>
         </listitem>
 
         <listitem>
           <para>You are expected to provide good internal code documentation
           with respect both to method signatures (<xref
-          linkend="glo_Javadoc"/>) and method implementation.</para>
+          linkend="glo_Javadoc"/>) and method implementation. Possible
+          problems involve:</para>
+
+          <glosslist>
+            <glossentry>
+              <glossterm>Compile time warnings</glossterm>
+
+              <glossdef>
+                <para>Activate most compiler warnings at
+                <guimenuitem>Window</guimenuitem> --&gt;
+                <guimenuitem>Preferences</guimenuitem> --&gt;
+                <guimenuitem>Java</guimenuitem> --&gt;
+                <guimenuitem>Compiler</guimenuitem>
+                --&gt;<guimenuitem>Errors/Warnings</guimenuitem>. This will
+                show potential compile time problems like dead / unnecessary /
+                unreachable code, unused variable values, shadowing conflicts
+                and so on:</para>
+
+                <mediaobject>
+                  <imageobject>
+                    <imagedata fileref="Ref/Screen/bonusJavadocCompileTimeProblems.png"/>
+                  </imageobject>
+                </mediaobject>
+              </glossdef>
+            </glossentry>
+
+            <glossentry xml:id="sd1BonusprojectActivateJavadocWarnings">
+              <glossterm><xref linkend="glo_Javadoc"/> mismatches</glossterm>
+
+              <glossdef>
+                <para>Your method's formal parameters, their type and the
+                return type must match your documentation. In the following
+                code snippet the method
+                <methodname>getPrimeFactors</methodname> does have neither a
+                parameter named <property>prime</property> nor
+                <property>frequency</property>:</para>
+
+                <mediaobject>
+                  <imageobject>
+                    <imagedata fileref="Ref/Screen/bonusJavadocMismatch.png"/>
+                  </imageobject>
+                </mediaobject>
+
+                <tip>
+                  <itemizedlist>
+                    <listitem>
+                      <para>Activate most <xref linkend="glo_Javadoc"/>
+                      related warnings in your IDE globally per workspace
+                      below <guimenuitem>Window</guimenuitem> --&gt;
+                      <guimenuitem>Preferences</guimenuitem> --&gt;
+                      <guimenuitem>Java</guimenuitem> --&gt;
+                      <guimenuitem>Compiler</guimenuitem> --&gt;
+                      <guimenuitem>Javadoc</guimenuitem>. You may as well
+                      activate them as per project settings below
+                      <guimenuitem>Project</guimenuitem> --&gt;
+                      <guimenuitem>Properties</guimenuitem> --&gt;
+                      <guimenuitem>Java Compiler</guimenuitem> --&gt;
+                      <guimenuitem>Javadoc</guimenuitem> if ticking
+                      <quote>Project specific settings</quote>. </para>
+                    </listitem>
+
+                    <listitem>
+                      <para>Actually generate the <xref
+                      linkend="glo_Javadoc"/> <xref linkend="glo_HTML"/> and
+                      see whether it will be useful / sufficient to a
+                      programmer using your <code>public</code>
+                      interface.</para>
+                    </listitem>
+                  </itemizedlist>
+                </tip>
+              </glossdef>
+            </glossentry>
+          </glosslist>
         </listitem>
 
         <listitem>
-          <para>You are expected to provide meaningful unit tests.</para>
+          <para>You are expected to provide meaningful unit tests:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>Try to cover all your implementation code and not just
+              isolated modules / methods.</para>
+            </listitem>
+
+            <listitem>
+              <para>If methods allow for null values write suitable
+              tests.</para>
+            </listitem>
+
+            <listitem>
+              <para>Test special cases: If a method expects i.e. an array of
+              strings it may be allowed having zero length.</para>
+            </listitem>
+          </itemizedlist>
         </listitem>
 
         <listitem>
           <para>Your resulting project should be easily installable /
           runnable.</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>Maven is a good starting point with respect both to test
+              integration and cross platform (Unix / Windows / Apple)
+              portability.</para>
+            </listitem>
+
+            <listitem>
+              <para>Avoid dependencies to local filesystem resources like
+              <filename>c:\users\xyz\testdata.txt</filename>.</para>
+            </listitem>
+          </itemizedlist>
+
+          <tip>
+            <para>Test the deployability of your project by installing it on
+            an untouched target platform (possibly of a different
+            hard/software architecture) and execute <command>mvn</command>
+            <option>test</option> (provided you do have written meaningful
+            unit tests).</para>
+          </tip>
         </listitem>
       </orderedlist>
     </section>
@@ -203,7 +314,7 @@
       xlink:href="https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes#Euler.27s_Sieve">Euler's
       sieve</link></title>
 
-      <para>The project's aim is about:</para>
+      <para>The project's goal is about:</para>
 
       <itemizedlist>
         <listitem>
@@ -211,9 +322,8 @@
         </listitem>
 
         <listitem>
-          <para>Using this set of pre - generated prime numbers for
-          decomposing arbitrary <code>int</code> values into prime factors
-          e.g.:</para>
+          <para>Using this set of pregenerated prime numbers for decomposing
+          arbitrary <code>int</code> values into prime factors e.g.:</para>
 
           <para>1050 = 2 * 3 * 5 * 5 * 7</para>
         </listitem>