Project Work Submission

Requirements for the submission

You must submit the following information by email to:

• A link to the working web page
• A link to the GitHub repository containing your code

I have provided a skeleton GitHub repository at github.com/AndrewCRMartin/biocomp2/ with a suggested layout for your code. You do not have to follow exactly this layout, but you are expected to do the following:

• It must be made completely clear who wrote which section of the code. i.e. the code for the front end, middle layer and database must be in three separate directories each containing a 'readme' file stating who was responsible for the code in that directory.
• Documentation for the code must be supplied in the form of comments within the code (headers for each file and for each function). In addition, there must be a document describing the API for each layer (database wrapper and business logic layers). Again, the authors of the document(s) must be identified.
• Commentary/reflection. You must each submit a short (2-5 pages of A4) explanatory essay/commentary on the work you have done. This should have a self-reflective element: How well did the development cycle within the group work? What were the challenges? What might they have done differently? What have you gained from this experience in terms of becoming a better programmer? You might include material (as separate files) not submitted as part of the main assignment. (For example, while not expected, we talked about the possibility of developing a parallel body of code in another language, other than Python).

NOTE: If you use a word processor for the documentation and/or commentary, you MUST also supply your documents as a PDF file.

Suggested submission

The provided skeleton directory is laid out as follows:

biocomp2/                    (Top directory)
|-- cgi-biocomp2             (All CGI scripts and layers under here)
|   |
|   |-- bl                   (The business logic layer)
|   |   |-- blapi.py         (The API imported by the CGI scripts)
|   |   |-- docs             (Documentation for the API plus your essay)
|   |   |   \-- README.md    
|   |   |
|   |   \-- README.md        (A brief description of the contents of this directory)
|   |
|   |-- cgi                  (The front end CGI script)
|   |   |-- docs             (Documentation for the CGI script plus your essay)
|   |   |   \-- README.md
|   |   |-- htmlutils.py     (CGI code - imports ../bl/blapi.py)
|   |   |-- listall.py       (CGI code - imports ../bl/blapi.py)
|   |   \-- README.md        (A brief description of the contents of this directory)
|   |
|   |-- config.py            (Configuration file used by all python scripts)
|   |
|   |-- db                   (The database access layer)
|   |   |-- dbapi.py         (The API imported by the business layer)
|   |   |-- docs             (Documentation for the database plus your essay)
|   |   |   \-- README.md
|   |   |
|   |   \-- README.md        (A brief description of the contents of this directory)
|   |
|   \-- README.md            (A brief description of the overall structure)
|
|-- createdb                 (Code to populate the database)
|   |-- docs                 (Documentation on how to run the code)
|   |   \-- README.md
|   |
|   \-- README.md            (A brief description of the contents of this directory)
|
|-- html                     (HTML for the main page)
|   |-- css                  (CSS used by the pages and CGI scripts)
|   |   \-- biocomp2.css
|   |
|   |-- index.html
|   \-- README.md            (A brief description of the contents of this directory)
|
|-- install.sh               (Ideally a script to install everything)
\-- README.md                (An overall description of the project)

Reflective Essay (2-5 pages)

1. Explain how you set about the project detailing:
1. how you interacted with the other members of the group
2. how you (as a group) came up with the requirements for the overall project
3. how you (as an individual) came up with the requirements for your contribution
2. How well did the development cycle work within the group?
3. You should document the development process - what stages did you go through and what steps did you take? Did you go through several iterations or did you spend a long time in design and then a relatively short development stage?
4. What strategies (if any) did you take for testing your code - particularly if other people's code wasn't ready?
5. Are there any known issues or bugs, or anything that doesn't work as specified?
6. You should discuss what worked well and what could have worked better - both with your code and the group interaction. Were there any particular problems? Conversely were there any solutions or ideas that you were particularly proud of?
7. Were there alternative strategies you could have used? (Either for the project design or implementation)
8. What do you think you gained out of the project? How has this experience helped you? What experience or insights have you gained?

Consequently I suggest headings of the form:

1. Approach to the project
1. Interaction with the team
2. Overall project requirements
3. Requirements for my contribution
2. Performance of the development cycle
3. The development process
4. Code testing
5. Known issues
6. What worked and what didn't - problems and solutions
7. Alternative strategies
8. Personal insights

Code documentation (1-2 pages per tier)

Note that this should not simply be a re-printing of the code with the comments in bold (or something similar).

In general:

• Provide a description of the function of subroutines and programs. It should describe WHAT the functions do not HOW they do it (such comments should appear in the code).
• Provide an explanation of the structure of the code - i.e. what calls what - decribing (perhaps as a diagram) how separate pieces of code or subroutines (and HTML for the front end) interact with one another.
• Explain how to install and run the software. For example, how are the programs run to populate the database? Are there other programs that must be run to calculate and store the information on chromosome codon usage before these are stored in the database? If so, how are these run?

For specific layers, the documentation should:

• Front-end provide a short end-user document, and explain what middle layer code was accessed and how the results were displayed in CGI scripts. You should document any semantic markup used.
• Business logic define the API provided to the front end in such a way that another programmer could implement a front end with reference to your document.
• Data access routines (which may be provided by the database programmer or the business logic programmer) define the API provided to the business logic in such a way that another programmer could implement the business logic with reference to your document.
• Database provide table definitions and UML diagrams (or equivalent) detailing indexes, primary and foreign keys, and any constraints.

Marking criteria

In general we will be taking a loose, "holistic" approach to marking so we are able to give credit where it has been earned rather than penalizing people for not doing enough in one area. You are expected to stretch yourselves!

However, criteria will include:

• How well does the web server meet the required brief?
• How easy is it to use?
• Is the 3-layer design properly implemented?
• Quality of the HTML
  • is it compatible with XHTML (or later) standards?
  • is all formatting done with CSS?
  • does it make appropriate use of semantic markup?
• Quality of code
  • is code properly laid out?
  • is it readable and understandable using suitable variable names?
  • does it use appropriate error and code checking?
  • is it properly commented? This should include a header at the top of each file and a docstring comment for each function. Comments must include author information.
  • are things like hard-coded pathnames, database details, etc appropriately placed to make installation on a different machine straightforward? At a minimum hard-coded information should be at the top of a file - ideally in a separate configuration module or in a file that is read by the code.
• Quality of documentation
  • is all code appropriately documented?
  • is the documentation clear and easy to understand?
  • is the interface well documented - either with a separate user manual or with appropriate help information on the web pages?
• Commentary/Reflection - are the following items addressed
  • How well did the development cycle within the group work?
  • What were the challenges?
  • What might they have done differently?
  • What have you gained from this experience in terms of becoming a better programmer?