Proposals and Reports

Software Engineering Large Practical

Today's Lecture

• I will begin with some general advice I've gleaned from reading some of your proposals
• I will talk about what to put in your reports

Originality

• Some of you are concerned with your proposal being something not terribly original
• Nobody said that your project had to be original, in fact I have not come across anyone suggesting that they will write a clone yet, but that would have been acceptable
• The purpose is to display you ability to engineer software, not come up with a creative plan

Originality

However

• That being said, I would like for this project to actually be rewarding for you
• Implementing a quick version of something that already exists might not be very engaging for you, and hence you are likely to spend less time on it
• If you are improving/changing one particular aspect, focus on doing that well first

Security

• A few of you are worried about security
• For this project you needn't worry too much about security storing passwords etc. for several reasons:
  • Most of you are doing a kind of proof-of-concept
  • Going into production would mean auditing your user-login procedure
  • Libraries and services exist to do this for you

Low Security Risks

• Most of you are not proposing to do any kind of service for which it would be particularly profitable to gain access to someone's account
• If someone gains access to my chess account, about the worst they could do is actually play a good move, slightly irritating my friends
• But there are (at least) two important security risks associated with low-security services

1. Impersonation

• Gaining access to someone's Facebook account might pose much of a security risk, in terms of money
  • They may very well be able to embarrass you
  • You may have sensitive data there, particularly of the sort banks use as security questions
• A bigger threat is that they impersonate you, in order to:
  • Extract money from friends and family, eg. A call for help
  • Gain access to other more sensitive accounts

2. Re-using Passwords

• Unfortunately many people use the same username/password for several different services
• Attackers can simply set up their own services, or attack a weak but popular one
• Relevant comic

Security

• For this project, there are basically two ways in which you can deal with these kinds of security concerns:
  1. Delegate user authentication
  2. Avoid user authentication

1. Delegate User Authentication

Internet Driving Licence

• It is common now for web applications to allow the user to login with one or several popular services
  • Google/Facebook/Twitter
• Many web application frameworks provide an easy access route to this
• If not, you can leave this undone and simply claim that this would be used in production
  • Try to make sure nothing you do prevents this

2. Avoid User Authentication

• You require users but do you really need user authentication?
• It may be that no harm is done upon gaining access, and accounts are intended to be anonymous anyway
• Hence you could just allow users to be whoever they say they are
  • This has the problem that if you later change your mind there are no stored means of authentication
• Alternatively, and more realistically, you should at least allow users to do as much on your site as they can without requiring a sign-up
  • In other words, allow them to consume content but maybe not create content

Cross Browser Compatibility

• Again not really necessary for this project
• I will be testing your applications on DiCE, which means Chrome or Firefox
• These are available for most platforms

Security/Browsers etc.

• More generally such concerns are a bit orthogonal to the actual project
• You might wish to work on such concerns, particularly if you proposal is a bit short on work load
• Of course, some things might be more intrinsic to your proposal, for example if you have implemented a password strength game

More Generally: Polish

• “How much polish should my application have?”
• Polish is referring to the more minor features which do not contribute to demonstrating the main idea
  • Eg. Allowing edits, blocking, spell-checking, auto-logout, keyboard shortcuts
  • All the small things that alone are minor but together make the application usable
• Another way of asking this is: “How complete/usable should my application be?”

More Generally: Polish

• This is largely a function of how ambitious your main proposal is
• Some of you have been very ambitious: multi-user open-world game system
  • Polish here is not likely to be necessary
• Some of you have a neat idea, but that is not greatly technically challenging: recipe database
  • In the simplest case a recipe database consists of one free text input box which is stored
  • More polish on this would allow a more sophisticated format for a recipe
  • In any case, to create enough work, you may have to do quite a bit of polishing

Implementation Language

Implementation Language

Implementation Language

Examples of the first

• A blog engine, accepts posts and comments, and displays those
• Discussion forum, similarly accepts comments and displays those
• Usage tracking
  • Travel logs
  • Exercise logs
  • Basically any kind of log
• Community information, beer recipes, knitting patterns

Implementation Language

Examples of the second

• Computation service eg. users upload mathematical models and you solve them and display the results as graphs
• Most games have some kind of game logic attached
• Popular services eventually have to combat spam or people mis-using the service:
  • eg. Creating many web-mail accounts and using them as free storage space

Implementation Language

Unfortunately

• The first kind often turns into the second kind
• Usage tracking: turns into data analysis on the the tracked data
• Community information, organisation, validation, tracking, user rewards

Implementation Language

User Ranking

• In fact a large part of the reason for having some kind of ranking was to partially force you into the second kind, the language dependent parts

Your Proposals

Common Comments

• Focus on the main interesting functionality
• If you had to demo your work next week, what would you work on?

Your Report

Software Engineering Large Practical

Your Honours/Minf Projects

• Next year you will embark upon an honours project
• Here is a random sample of project proposals:
  1. Program atomization using the LLVM (Low Level Virtual Machine) compiler infrastructure
  2. 3D Silicon Fly-through
  3. Predicting High-latency Memory Operations
  4. Software development for electrophysiological data analysis
  5. Android games for the Blind
  6. Facebook for Babies

Implementing Software

Honours Project

• In many of these projects you will be implementing some software for a specific purpose
• In order to achieve this it will likely be a good idea to:
  • Use source code control
  • Use an issue tracker, a profiler, a debugger
  • Automate a comprehensive test suite and a coverage analyser
  • Refactor for optimal design
• However, you do not get directly marked on any of this

Honours Project: Marking

Dissertation

• You are marked solely on your dissertation
• You will get marks for good software development practices, but only if you describe them well in your dissertation
• It is sadly very common to see students do a lot of very good implementation work only to fail to describe it in the dissertation
• Arrogance plays a part here: formal writing is difficult and many students seem not to appreciate that

This Project: Your Report

• View the report you hand-in for this project as a practice for the one you will write next year
• This coursework is marked on the strength of both the implementation and the report
• This coursework represents a good half-way house between most coursework which is soley marked on the work you have done and the honours project in which you are solely marked on your description of the work you have done

Convincing Writing

• In formal writing you are trying to convince the reader of some position that you hold
• This is an excellent skill to obtain, you will need it frequently
  • “We should use Java for this”
  • “We should schedule at least a month for this work”
  • “Why are you using the Observer pattern? It is inapplicable here”
• Being correct is not good enough
• Writing good software is not good enough
  • You may well have to convince people that what you have achieved was challenging

Convincing Writing

But you did not persuade me

• I told you so Is the refrain of people who could not convince you of the correct course of action, despite the fact that we now know they had the huge advantage of actually being correct

Formal Writing

• Formal writing is not just dictated conversation
  • In particular it is one way communication
  • It is difficult to write but easy to read
  • The time and effort spent by the author is hopefully repaid by the many readers (unfortunately not so much in this case)
• Each of your paragraphs should make exactly one point

Paraphrasing from Proposals

I will write a kick-boxing web application. I will write it in Ruby and I think I will use Bootstrap because I am already proficient in Ruby and the application will require access to a database and Ruby has a nice Gem for SQLite. Users will be ranked by the number of bouts that they have won with validation of claimed victories done by the defeated combatant.

Formal Writing

• Make your thesis obvious throughout
  • The reader should never be in any doubt as to what your thesis is
  • If you believe they may be in doubt, it rarely hurts to remind them
  • Relate each point you make, to your thesis/main point

What is Your Thesis?

• Your thesis is:
  • “My implementation is solid and I have used excellent software development practices, I therefore deserve at least X out of 100”
• If you are uncomfortable suggesting your own mark then:
  • “My implementation is solid and I have used excellent software development practices, I therefore deserve a high mark”
• Anchoring is a related cognitive bias

Formal Writing

A Simple Recipe

Formal Writing

A Simple Recipe

Formal Writing

A Simple Recipe

Formal Writing

Focus

• Stay on topic:
  • Each paragraph should have a clear relationship to the main topic
    • If it does not it is a good candidate for elimination
  • Staying on topic does not mean being one sided
    • In particular if you are arguing a certain point, it is a good idea to acknowledge evidence against that point
    • This helps define and make clear exactly what you are point you are making
    • It is often the case that you are attempting to make the point that “A implies B”, and it is very easy for the reader to misunderstand your argument as a case for B

Formal Writing

Conciseness

• This is perhaps the most difficult part of writing
• Writing down your thoughts is not formal writing, it is simply recording
• Generally speaking writing is similar to code in that less is often more
• When writing formally, it is a common error to describe the unnecessary:
  • for example, a critique of an article, does not need to directly mention reading the article, if you are writing about it is assumed that you have read it
  • No: “Whilst reading the paper I came to the conclusion that I disagree with the author.”
  • Yes: “I disagree with the main thesis of the paper.”

Formal Writing

Conciseness

• For you: that means:
  • No: Whilst I was working on the implementation of my web application I decided to use Bootstrap because ...
  • Yes: I decided to use Bootstrap because ...

Formal Writing

Conciseness: Redundancy

• Avoid redundancy
  • Often, after finishing, you can look through and remove some phrases/sentences, maybe even paragraphs
  • For each paragraph decide what would be the effect on your article if you deleted that paragraph
  • Often your point will be better made once this is done

Formal Writing

promises promises

• I'm not sure why, but promises are very common in student writing
  • “I will discuss certain aspects of X”
  • Unfortunately this is often in an article/dissertation with X in the title
  • “In the end I will describe my conclusion”
• It's not the promise that is wrong, it is the vagueness, so please, no need for teasers or promises of clarification
• Just be clear from the start:
  • “The aspects of my implementation that I will discuss positively are: ...., I will also concede limitations/deficiencies of my implementation which are: .... ”

Formal Writing

promises promises

• More generally for formal writing: Everything important goes in the introduction and conclusions
• People often decide whether or not to read your article based on one or both of these two sections

Formal Writing

Ambiguity

• Try to avoid ambiguous references
  • Add a noun to disambiguate
  • “I disagree with this because ...”
  • “I disagree with this paper because ...”
  • “I disagree with this argument because ...”
  • “I disagree with this sentence because ...”

Editing - Refactoring

• Refactoring is a very important part of the software development process
• Editing your article is equivalent to refactoring and just as important
• Here I am not referring to the process of checking for spelling and grammar errors
• Here, editing is strictly to mean changing the semantic content of your article
• The things I have said above are mostly refactoring

Formal Writing

• I am far more forgiving of spelling and grammatical errors
• That said, using a spell checker does not hurt
• Your writing should be understandable, if that means sticking to grammar rules, then so be it

Formal Writing

Quick Refresher

Formal Writing

• I don’t care much about capitalisation
• I don’t care much about hyphens, whether used when not needed or omitted when required
  • But as always, do be careful that you are not being ambiguous
  • fake geek girl, fake-geek girl, fake geek-girl
  • smart software developers ?

Formal Writing

• I don’t care much about American vs British (unfortunately it has to be, some form of, English though)
  • I do not even care if you are consistent within a single article
• However, other people do, so it is up to you to decide who your audience is.
  • I suggest British because then you can easily search for ‘z’

Formal Writing

Title

• Choose a good title!
• Ideally a reader should be able to hazard a decent guess at the main point of your article, just from the title

Formal Writing

• A final tip which is at odds of almost everything else I have said
Entertain the reader
The level to which you can do this depends on how formal the writing is
This is often hard to do whilst still being clear
Some things are difficult and cannot be summed up in a few bullet points

Formal Writing

• Particular thanks to Dr James Bednar whose notes on formal writing were much of the basis for these guidelines
• Well-worth reading in their own right
• here they are

Word/Page Limits

• In coursework assignments such as these you often are given a minimum word count
• For these assignments the word-count estimates are intended to give you an idea of the depth of your discussion
• For this assignment I'm looking for a report of between 5 and 10 pages
  • depending of course on your formatting, diagrams (if any) etc.
• This is merely a guideline
• There is no minimum limit

Word/Page Limits

Maximum

• In less contrived situations you are often given a maximum limit
• There is always an implied maximum limit that people will read
• I will say 10, 000 words is a hard limit
  • If you wish to exceed this, contact me
  • Otherwise, when marking, 10K words is the amount which I will be obliged to read
  • Of course if you are entertaining then I will continue, but to be entertaining you area also likely concise

Your Report: Contents

• Your report is there to convince me:
  • You have followed sound software development practices
  • You have done an adequate amount of work
  • You have made well reasoned decisions
  • Any deficiences are well justified or
  • You have now learnt what you should have done instead

Your Report: Contents

Software Development Practices

• If you are using your source code control well, this should allow me to figure out how good your software development process was
• But why rely on my detective skills?
• In particular a good thing to describe in your report is the structure of your source code that might not be obvious:
  • This does not mean tell what things are in which files
  • This means, tell me why the program is divided in that manner

Your Report: Contents

Software Development Practices

• In addition the report is a good place to explain any refactorings of which you are particularly proud:
  • Explain why it was necessary/warranted
  • Explain how your refactor solves the problem it was intended for
  • Does your refactor make some part more general, or more readable, or both?
• “My design is adaptable because ...”
• “The look and feel of my web application sucks, but all a designer need only edit the statically served main.css file”

Your Report: Contents

You have done an adequate amount of work

• You may feel that that needs no justification, in particular you may feel that the functionality speaks for itself
• But, you may feel that the amount of work is not fully appreciated simply by looking at the functionality, so:
  • Explain any difficulties you had
  • Explain how you overcame those difficulties

Your Report: Contents

You have made well reasoned decisions

• Describe any decisions which you think are interesting
• In particular anything where you think the obvious answer is wrong and you want to explain your reasoning behind what seems like a surprising choice
  • “At first glance it seems silly to have used more than one general purpose language for the back-end, but ....”

Your Report: Contents

Any deficiences are well justified

• This is mostly about saying what you would do if you had more time
• Examples:
  • “I have not implemented user authentication because it is not interesting and other features demonstrate value much more clearly”
  • “Users cannot edit their posts once submitted, but clearly adding such a feature does not require a major re-design”

Your Report: Contents

Or, lessons were learnt

• As stated previously, failure is how we learn
• Failure is a good thing, provided you learn what not to do
• So, describe anything you now recognise as a mistake:
  • Explain why you thought it was correct initially
  • Why you now believe it was incorrect
  • What you think you should have done instead

Your Report: Structure

A Possible Structure

1. Introduction: what works, are you happy with what you have?
2. Difficulties: what did you spend more time on than you would have hoped
3. Structure: and how you arrived at that structure, major refactorings, what makes you think it is the correct one now
4. My test strategy: This is how I tested my implementation, this is how I know I have tested enough
5. Deficiencies: Both justified and caused by errors in decision making
6. Things I would do differently: did I choose the correct languages/technologies, where I would go from here? Start again?
7. Conclusion: are you happy with what you have?

Refactoring, Optimisation & Testing

Software Engineering Large Practical

Automation

• Tests are really just a special case of the maxim:
  • “Never do what the computer can do for you”
• Any activity that requires more than one step, should be reduced to exactly one step
• Code as if you have anterograde amnesia
  • Everything you do today, you will forget, so it must be recorded
  • If there is specific software for recording it, such as an issue tracker then use it

Instructions

• If you have to write down instructions, such as installation instructions:
  • Ask yourself whether or not you can simply make those instructions executable

Any Questions