University Hand-in Template

Document Sample
University Hand-in Template Powered By Docstoc
					NetWork: Process Report
      MISCELLENIA




                                     BEN HOOD
    BACHELOR OF SCIENCE: SOFTWARE ENGINEERING
                                       99811903
                                   2,639 WORDS


Ben Hood              Page 1              23/02/2010
  Contents
Contents............................................................................................................................. 2
Introduction ...................................................................................................................... 3
  Summary ....................................................................................................................... 3
Coding Practices ............................................................................................................... 4
  If (null == boolValue) { } .............................................................................................. 4
  If (Contains) { lock() { if (Contains) { } } } .................................................................. 4
  Virtual or Abstract? ..................................................................................................... 6
  OnComplete vs. CompleteEvent ............................................................................... 6
  Programming to Interfaces (pros and cons) ............................................................. 7
  Comments ..................................................................................................................... 8
Choice of Tools ............................................................................................................... 10
  Manual vs. Automated .............................................................................................. 10
  Development Tools .................................................................................................... 10
  Manual docs ................................................................................................................ 12
  Automated docs ......................................................................................................... 13




Ben Hood                                                       Page 2                                                   23/02/2010
 Introduction
Summary
In this document, I will discuss additional items that relate to many areas of the
design and development of the application. I will discuss my thoughts on each
item, and present a case for why I felt my actions were appropriate.
I will also discuss the various tools and methods I have used during
development of both this application and its documentation, and state the
advantages and disadvantages of each.




Ben Hood                               Page 3                             23/02/2010
  Coding Practices
If (null == boolValue) { }
During the process of coding the application, I have consistently written
comparison operators with the non-assignable value first where possible (i.e.
(true == boolValue) but not (identityA.Equals(identityB))). The example below is
taken from the ConsoleOutputRedirect class in its Singleton construction
method.

    COMPARISON BY NON-ASSIGNABLE FIRST
    public static ConsoleOutputRedirect GetInstance() {
        if (null == ConsoleOutputRedirect.instance) {
            ConsoleOutputRedirect.instance = new ConsoleOutputRedirect();
        }
        return ConsoleOutputRedirect.instance;
    }


The reason I have done this is to ensure that the bug demonstrated in the
following code would not occur during development.

    ACCIDENTAL ASSIGNMENT BUG
    public bool AccidentalAssignmentBug() {
        bool result = (5 > 6);
        // Here, the accidental use of = instead of == means that result will
        // be set to true, even though 5 is not greater than 6
        if (result = true) {
            System.Console.WriteLine("Result is True!");
        }
        return result;
    }



Although the .net compiler will throw an error in the case of the first code if
using a single = operator (since it would not resolve to a Boolean value) I felt that
the consistent use of a single style would be beneficial to the application’s code. I
feel that in some cases, this has actually reduced the readability of the code to a
small extent, but is a small price to pay for avoiding such difficult to track bugs.

If (Contains) { lock() { if (Contains) { } } }
In many areas of the application, I have collections or remote objects that require
transactional operations, and so need some form of locking. Particularly in the
case of adding an item to a collection, where the collection must not contain more
than one instance of an item, I need to ensure a lock on the collection before



Ben Hood                                         Page 4                         23/02/2010
testing it (for thread-safety). As discussed in the Process Report – the network
layer: Multithreading: Transactions between threads, the following example uses
the SyncRoot collection property to provide thread-safe access to the collection.

   THREAD-SAFE ACCESS TO AN ARRAYLIST
   private System.Collections.ArrayList list = new System.Collections.ArrayList();
   public void AddIfNotPresent(object item) {

       // Lock the list for thread-safe access
       lock (list.SyncRoot) {

           // If the list doesn't contain the item, add it
           if (!list.Contains(item)) {
               list.Add(item);
           }
       }
   }


The above code is fine, but what if the list already contains the item? Acquiring a
lock is expensive in terms of time and resources, and doing so in a networked
environment is a serious consideration. Therefore, where pragmatic, I have
checked for item presence before acquiring the lock. In contrast, when removing
the item (where checking then locking could result in errors with asynchronous
adds) I lock the list directly:

   IMPROVED THREAD-SAFE ACCESS TO AN
   ARRAYLIST
   private System.Collections.ArrayList list = new System.Collections.ArrayList();
   public void AddIfNotPresent(object item) {
       // If the list doesn't contain the item, then acquire a lock
       if (!list.Contains(item)) {
           // Lock the list for thread-safe access
           lock (list.SyncRoot) {
               // If the list still doesn't contain the item, add it
               if (!list.Contains(item)) {
                   list.Add(item);
               }
           }
       }
   }
   public void RemoveIfPresent(object item) {
       // Lock the list for thread-safe access
       lock (list.SyncRoot) {
           // If the list still doesn't contain the item, add it
           // (no test required, since ArrayList will not remove
           // an item that it does not contain
           list.Remove(item);
       }
   }




Ben Hood                                 Page 5                                23/02/2010
Virtual or Abstract?
In several instances, I needed to make a decision about how to force classes to
implement the functionality I required of them. A perfect example of this is the
Plugins.MarshalByRefService class, which ensures that the service provides an
implementation of the Attach and Detach methods required by the network
layer’s Mesh class. The MarshalByRefService is also serialisable (to support
network state persistence), and so is marked with the SerializableAttribute; the
following passages are also included in the Project Documentation – the project
architecture.
As a developer of the MarshalByRefService super class, I realised I may need to
support custom serialisation in future versions of the class. I therefore chose to
implement the ISerialisable interface, and to perform custom serialisation there. I
also realised that subclassed services may also benefit from using custom
serialisation, and so chose to expose the process to these services using a
traditional gang-of-four template method.
However, some services may not require use of the serialisation, since they may
be largely stateless – or their state may depend only upon attached peers. I
therefore set the GetServiceData template method to be virtual, and in this way
was able to provide access to the serialisation and de-serialisation process
without enforcing it. Please see the Project Documentation – the Project
Architecture: NetWork.Plugins and Process Report – The CVS Layer: A Plug-in
Architecture: Reflection for more information).

OnComplete vs. CompleteEvent
In addition to the above development of thought concerning the use of template
methods, I also faced several instances where the template method could be
argued as a protected event instead of a subclassed method.
There are pros and cons to each approach. Using a template method is simple to
develop (and maintain), and allows a class hierarchy to enforce defined methods
to be implemented in the subclasses using the abstract keyword. The event
method is less enforced (although you can receive run-time exceptions at the
parent), but allows for calls to multiple ChildMethods to be defined at the child
instead of the parent.
A simple example of these two contrasting methods is shown in the attached
demonstration project – ‘TemplateVsProtectedEventDemo’ – available on the
project CD. A snippet of the source code is as follows, and demonstrates the
similarities and differences between the two (largely concerning class extension).




Ben Hood                              Page 6                              23/02/2010
   TEMPLATE METHOD EXAMPLE
   // Using the template method design pattern:
   public abstract class TemplateParent {
       public void WriteSomething() {
           Console.WriteLine(this.ChildMethod());
       }
       protected abstract string ChildMethod();
   }


   public class TemplateChild : TemplateParent {

       protected sealed override string ChildMethod() {
           return "Some TemplateChild text";
       }
   }


   PROTECTED EVENT EXAMPLE
   // Using a protected event pattern:
   public class ProtectedEventParent : IParent {
       public void WriteSomething() {
           if (null != this.WriteSomethingEvent) {
               this.WriteSomethingEvent();
           }
       }
       protected delegate void WriteSomethingEventHandler();
       protected event WriteSomethingEventHandler WriteSomethingEvent;
   }


   public class ProtectedEventChild : ProtectedEventParent {
       public ProtectedEventChild() {
           base.WriteSomethingEvent += new
               WriteSomethingEventHandler(this.ChildMethod);
       }
       private void ChildMethod() {
           Console.WriteLine("Some ProtectedEventChild text");
       }
   }



Programming to Interfaces (pros and cons)
During development of this application, I have used the highest ancestor
interface relevant to the programming context of each object to define the
references to each object. This means that I can easily change the members used
by an object later for more sophisticated or optimised subclasses without
changing the usage code, since the new subclass could conform to the existing
interface.
This may seem obvious, but has been a fundamental stage in the development of
this application, as it has led me to build my own custom classes to these




Ben Hood                                 Page 7                          23/02/2010
interfaces also, which has resulted in components re-usable outside of this
application’s domain.

   PROGRAMMING TO AN INTERFACE
   internal class Cache : MarshalByRefObject {

       private IDictionary blobs = new Hashtable();
       private DirectoryInfo rootDirectory;
       // ...


As can be seen from the above example, the NetWork.Cvs.Cache object keeps an
internal dictionary of blobs. Because I only have need of the functionality
defined by IDictionary, and not any specific to the Hashtable implementation, I
can use the IDictionary interface to ensure that the object provides a consistent
functionality. I could later swap the Hashtable instance with a custom
dictionary, specially optimised for use with Blobs, and not need to change any
other code in this class. Likewise with input parameters and return values, I
have tried to keep to the highest ancestor interface relevant to the context of use,
and so have allowed any conformant object be used in such parameters.
In the above example, I have also used the DirectoryInfo class as an explicit
declaration of the functionality I require from the rootDirectory object. While, in
the case of the Cache class, I do not use any functionality not defined in the
DirectoryInfo’s superclass FileSystemInfo, I have used the reference specifically
to the DirectoryInfo due to the context that this object will be used in. A FileInfo
object also extends FileSystemInfo, but would be inappropriate for use as
rootDirectory, because its context would be wrong – regardless of whether I use
any functionality not defined in FileSystemInfo.
I have therefore found this method of programming not only beneficial to my
construction and extension of objects, but to ensuring consistency of member
context within each class.

Comments
Beyond the standard inclusion of development comments and member
documentation, I have found the use of .net region tags very useful when
commenting code for later developers to view. I have used region tags
consistently through the project to define subsections of code unobtrusively, with
the benefits of being able to thus ‘collapse’ blocks of related code, and of defining
a comment for both the start and end of a programming context. The following
examples are taken from the NetWork.Gooey.Controls.ImageButton class.




Ben Hood                                 Page 8                            23/02/2010
  USING REGIONS TO HELP DOCUMENT CODE




Ben Hood            Page 9              23/02/2010
 Choice of Tools
Manual vs. Automated
Many times during development of this project, I have faced decisions over
which tools to use. The first choice I had to make in each case was whether to
use an automated or a manual tool to complete the task.
The criteria I have employed when choosing each tool to complete this project
has been as follows:
      Would the task benefit from human input, or can it use existing information to
       complete its operation?
     Would it be faster/easier to use the tools I am already using?
     Is it compatible with the tools and formats I am using already?
     Does it look usable (check screenshots before downloading trial version)?
As can be seen above, the first question I asked of any task as I approached it was
whether it would benefit from my input. The response to this varied – simple
tasks such as creating a project’s skeleton were quite acceptable as generated
from a standard template, and gave me more time to concentrate on their content
rather than their creation. On the other hand, complex or creative tasks could
not be performed by an automated tool, and instead benefited from my
intervention.
As this research into tools continued, I increasingly found it was rarely the case I
had a purely manual or purely automated task. Instead, I found that parts of
each task benefited from being automated, while others were better performed
myself. A perfect example of this is the application comments – the shortcut in
Visual Studio (‘///’) .net automatically created a skeleton comments structure,
which I could then fill in myself (a process a computer could never do).
Likewise, I have used Together Control Centre to manage and synchronise the
UML structure, but have developed this UML structure manually.
I have hence concluded that there are no tasks that I could entirely automate,
since the content for the tasks must come from somewhere. However, I could
use existing tools to help me create this content faster, and so spend more time
improving the content, instead of fiddling with the details.

Development Tools
To develop the application, I have used Microsoft Visual Studio .net 2002 and
TogetherSoft (now Borland) Control Centre 6.0.1. I chose Visual Studio .net
because I had worked with it before, and was confident of its functionality, and
was able to download and use under The University of Brighton’s MSDN


Ben Hood                               Page 10                             23/02/2010
academic licence. This IDE is the currently the most developed and integrated
that I have seen for the .net environment – an inexcusable responsibility of the
developers, since it was developed in parallel to the .net framework.
Alternatives include the free SharpDevelop tool, available from ic#code
(http://www.icsharpcode.net/OpenSource/SD/), or Borland’s C#Builder
(http://www.borland.com/csharpbuilder/index.html). However, SharpDevelop
was still very much a developing application during the early stages of this
project, and I needed a solid platform for coding and testing; C#Builder was not
even available during the early stages of this project.
The limited number of UML applications available with C# compatibility is a
factor would have been a serious drawback to the development of this project,
had I not found a suitable tool. Of the available, Together Control Centre was
another application that I was most familiar with – an important factor when
deciding upon a platform to use, since it would influence the time I spent
learning the tools. Alternative tools included
    Rational XDE .net (http://www.rational.com/products/xde/dotneted/index.jsp)
    Microsoft Visio 2002 (http://www.microsoft.com/office/visio/default.asp)
    Prosac# (http://www.prosa.fi/eng/pr2Csharp.htm)
    MetaMill (http://www.metamill.com/product.html)
    WithClass (http://www.microgold.com/)
    ObjectIF (http://www.microtool.de/objectiF/en/index.htm)
    and more recently MagicDraw (http://www.magicdraw.com/)
Ideally, I wanted a tool that would integrate into my choice of Visual Studio, and
so minimise the amount of manual roundtrip I would have to control. MetaMill,
MagicDraw, Together Control Centre and WithClass are developed as
standalone products, and so I initially deemed them not suitable. I next
considered the licences of the products, as I would need to use them for more
than the standard 30-day trial period. The only remaining product was Visio
2002, which came under the University MSDN licence.
However, upon trying Visio, I realised that it would not perform any form of
interaction between my UML and code – I would therefore have to develop the
application twice, once in UML, and then transpose it to the code environment.
Additional software was available (http://www.ddddata.com/umlexporter/,
http://www.csharptoday.com/catalogue/csharpcontent/20020429_01.html) but I
felt this would only complicate matters, and refute the objective of a simple
transition between UML and code.
Based on code synchronisation, my next choice was to use TogetherSoft, which
was available under the University of Brighton licence. After installing it, I
found it less difficult than I had expected to keep the project in sync with the


Ben Hood                              Page 11                            23/02/2010
UML generated code, since both Visual Studio and TogetherSoft could
synchronise with changes made outside of their environment automatically
(although I did not use this feature frequently – preferring a manual copy
between two separate directory structures).

Manual docs
To write the manual documentation, and draw the included diagrams, I used
Microsoft Word XP, which is part of the Office XP installation available under
the University MSDN academic licence. Although I could have done the
diagrams in Visio without difficulty of importing, I found Word XP adequate. A
further advantage of using Word is that I know it is supported at University, and
hence have been able to share my work with my project tutor to keep a
continuous feedback. I could have used Sun StarOffice
(http://wwws.sun.com/software/star/staroffice/) for this task, but felt that I had
found a suitable solution using Word, and did not wish to learn a new
environment and so compromise my available time.
Since I was already familiar with Word, I found it easy to use, and that it did not
detract from my working environment. I have used its spell check and custom
grammar check features to ensure a clear and readable output. Furthermore, I
had already developed a standard Word template containing suitable formatting
and in a visually pleasing layout, so could re-use this to unify the format of all
my documentation. I have also added shortcut keys and outlining values to this
template for standard formats, so that I can compile the manual documentation
with minimal distraction.
However, I realise that Word documents are not accessible to all users due to
licensing fees imposed by Microsoft. I have tried to make all the documents
available as either HTML or PDF, for which there is a free support on most
operating systems. To generate the PDF files I used PDF 995
(http://www.pdf995.com/), which is available as an ad-supported printer driver,
which redirects to a user-specified Adobe Acrobat (.pdf) save file.
I felt that the documentation of the UML class diagrams was most suitable as
part of the diagram itself, each document tag could then be graphically
associated with UML class elements or members as appropriate. The
documentation of the UML I had to do manually in the TogetherSoft
environment, and manually link it with the appropriate class elements. This was
time consuming, but I feel it was worthwhile, since the notation is best expressed
in this form. Fortunately, TogetherSoft is compatible with the Windows
clipboard, as I later realised that some of the diagrams were too large with the
documentation to include clearly in the Word document. I was therefore able to


Ben Hood                              Page 12                             23/02/2010
copy the text from one format to the other with little difficulty, and so overcome
this problem.

Automated docs
Since I had the UML class diagrams in TogetherSoft, I felt it pragmatic to use the
tools provided by TogetherSoft to make my UML into an accessible form. I used
TogetherSoft Control Centre’s Generate HTML command to build HTML
hierarchies, which I have made available on the accompanying CD. I also used
the Control Centre’s Copy to Bitmap command to save the UML diagrams as
bitmap images on my computer’s memory, and then paste them into Word.
These were then saved as part of the Word document.
The comments I had written within the code itself I felt were a valuable tool to a
future developer of the project. I used the c# compiler to generate an XML
document from each compiled class (quickly configurable using the Visual
Studio Tools menu), and then used an automated documenting tool – Ndoc
(http://ndoc.sourceforge.net/) – to generate an interlinked HTML structure and
compiled Windows help (.chm) file from this.
I have also used some automated testing tools, and these are discussed in the
Project Documentation – Testing document.
I feel that, by using automated tools for these trivial but time-consuming tasks, I
have allowed myself more time to work on the documentation of this project,
and on developing and testing it.




Ben Hood                              Page 13                              23/02/2010

				
DOCUMENT INFO
Shared By:
Categories:
Stats:
views:4
posted:2/23/2010
language:English
pages:13
Description: University Hand-in Template