Difference between revisions of "Coding Convention"

From Developer Documents
Jump to navigation Jump to search
m
m
Line 72: Line 72:
 
<div style="background: #f3fff3;">
 
<div style="background: #f3fff3;">
 
<syntaxhighlight lang="java">     
 
<syntaxhighlight lang="java">     
     void read(InputStream is) {
+
     Object deserialize(InputStream is) {
 
         int x = is.read();
 
         int x = is.read();
 +
        ...
 +
        return result;
 
     }
 
     }
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 89: Line 91:
 
<div style="background: #fff3f3;">
 
<div style="background: #fff3f3;">
 
<syntaxhighlight lang="java">     
 
<syntaxhighlight lang="java">     
     void read(InputStream is) {
+
     Object deserialize(InputStream is) {
 
         if ( is == null ) throw IllegalArgumentException("Non-null argument");
 
         if ( is == null ) throw IllegalArgumentException("Non-null argument");
         int x = is.read();
+
         ...
 +
        return result;
 
     }  
 
     }  
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 108: Line 111:
 
<div style="background: #fffff3;">
 
<div style="background: #fffff3;">
 
<syntaxhighlight lang="java" style="background: #dfd;">     
 
<syntaxhighlight lang="java" style="background: #dfd;">     
     void read(InputStream is) {
+
     Object deserialize(InputStream is) {
 
         assert( is != null );
 
         assert( is != null );
         int x = is.read();
+
         ...
 +
        return result;
 
     }
 
     }
 
</syntaxhighlight>
 
</syntaxhighlight>
 
<br/>
 
<br/>
 
</div>
 
</div>

Revision as of 10:09, 13 October 2010

Simantics coding conventions are gathered in this document.

Argument Assumption

  • All method arguments are non-null unless explicitely stated otherwise in documentation.

<syntaxhighlight lang="java">

   /**
     * Read the object from a file.
     *
     * @param file 
     */
   void read(File file);
   /**
     * Write or remove existing value.
     *
     * @param newValue new value or null</t> to remove the existing value
     */
   void setValue(Object newValue);

</syntaxhighlight>


Non-null assumption applies in undocumented methods aswell. This method mustn't be called with a null argument.

<syntaxhighlight lang="java">

   void read(InputStream is);

</syntaxhighlight>


Return value assumption

  • All return values are non-null unless explicitely stated otherwise in documentation.

<syntaxhighlight lang="java">

   /**
     * Get the value
     *
     * @return the value
     */
   Object get() throws ValueUnavailableException;
   /**
     * Get possibly existing value
     *
     * @return the value is exists, otherwise null
     */
   Object get();

</syntaxhighlight>


Non-null assumption applies in undocumented methods too. There is always a non-null value returned from this method.

<syntaxhighlight lang="java">

   Object get();

</syntaxhighlight>


Trust your assumptions

  • You have a code of conduct - give it a chance.

The callee can trust the caller.

<syntaxhighlight lang="java">

   Object deserialize(InputStream is) {
       int x = is.read();
       ...
       return result;
   }

</syntaxhighlight>

And the caller the callee.

<syntaxhighlight lang="java">

   System.out.println( serialiser.deserialize( is ) );

</syntaxhighlight>

There is no need to do redundant checking, especially at run-time.

<syntaxhighlight lang="java">

   Object deserialize(InputStream is) {
       if ( is == null ) throw IllegalArgumentException("Non-null argument");
       ...
       return result;
   } 

</syntaxhighlight>

Nor caller.

<syntaxhighlight lang="java">

   Object x = serializer.deserialize( is );
   if ( x != null ) System.out.println( x );

</syntaxhighlight>

Use assertions if you must. It sometimes improve quality and debuggability.

<syntaxhighlight lang="java" style="background: #dfd;">

   Object deserialize(InputStream is) {
       assert( is != null );
       ...
       return result;
   }

</syntaxhighlight>