Building on the shoulders of giants

10 Feb

Building on the shoulders of giants

There is definitely a trade-off to be considered when using existing software. On the one hand, there is a learning curve: it takes a long time to find your way around the codebase and learn the purpose of each file.

In addition to a big learning curve, it can be difficult to place the blame if you encounter a bug:

Is it a bug in the open source software?
Is it a bug because of the way we’re using the open source software (in a manner it was not intended for)?
Is it a bug that we introduced in our code modifications?

In comparison, it is tempting to build software from scratch because of the lower learning curve; the project is developed incrementally and as a developer you gradually introduce yourself to new concepts and files, perhaps arriving at a project of a similar size to existing open source projects but having eased your way into the learning process.

Building from scratch is certainly more time-consuming. If a software system takes 100 hours to build from scratch, it is better to spend 10 hours learning an existing system and modifying it for your own uses. It is also likely to be better engineered, since it is likely to have had more developer hours invested in refining it.

Early on in my Major Project investigations I discovered Emcod; “an innovative project which aims to broaden Access to justice through use of Online dispute resolution”. It is an open-source tool designed for a LAMP server (Apache, MySQL, PHP).

I had hoped to use it as a basis for my Major Project, but on closer inspection this might not be a good idea.

It’s unclear what the code actually does! According to the website, Emcod “allows providers of Online dispute resolution to measure the costs and quality of their services”. How it does this is unclear, but it does suggest that the software does not actually provide the online dispute resolution process itself.
The website is poor. Though there are some installation instructions and a download to the source code, there are two items of text that look like links (and presumably were intended to become links one day) – these are ‘User manual’ and ‘Watch video’.
Due to the poor website and general lack of information, it’s hard to find out exactly when the code was released, but the download link (http://www.emcod.net/wp-content/uploads/2012/01/emcod.tar.gz) suggests January 2012. This is a stagnant codebase – it has not been updated since then.

In spite of any good documentation or description, I thought it would be a worthy investment of time to at least try and get the software up and running (as I have access to my own cloud LAMP server) to see if it would meet my needs.

An alternative open source framework to begin with is HumHub – a “Flexible, Open Source Social Network Kit”. ODR platforms aren’t social networks, but there are aspects of social activity such as Case timelines, private communication, “groups” of Agents in the same network (their Company), and so on. Also, additional functionality such as file upload facilities and user authorisation would be useful modules to reuse.

One of the pluses of HumHub, according to its website, is its flexibility. “With a powerful module system you can extend HumHub by using third party tools, writing your own or connect existing software”, so it should be possible to plug in all manner of functionality.

Emcod

Emcod was nice and easy to install:

And it handled login nicely:

But, sure enough, this didn’t look like online dispute resolution software.

It’s madness that I had to install the software to actually find out what it does. It was a long shot, but unfortunately this was not a suitable framework to build upon.

HumHub

Again, this was nice and easy to install. Below is a screenshot after having logged in and set up a profile.

HumHub has a concept of “spaces”, effectively groups where there is a central board everyone in the space can write to. This could be the basic underpinning of Case communication, if I can programmatically generate spaces.

HumHub has a modular system such that you can install and uninstall modules freely, and develop your own. I may be able to hook into rendering functions and so on, and add disputes as a function.

There’s no getting around the fact that HumHub was not intended to be an ODR platform. But what it DOES do for us is handle authorisation, authentication, profile management, and so on, so could be worth considering further.

Its repository is very active, and well documented, though there is a large backlog of issues.

I need to balance whether or not it is worth pursuing HumHub.

HumHub – Advantages

Actively maintained
Modular support
Built-in functionality that we need, including:
- Registration
- Login
- Notifications
- Concept of a central “space” for communication
- Attractive UI

HumHub – Disadvantages

A lot needs to be changed – e.g. “liking” evidence is not appropriate!
Although developed modularly, it may not provide enough hooks for all the functionality I’ll need to develop
Large codebase to get to grips with, therefore a large learning curve
No getting away from the fact that the purpose of this software is fundamentally different to ODR platforms.
We don’t want to be locked into third-party consumerist bubble.
Release under the AGPL license restricts what we can do with our codebase (i.e. we cannot stay closed-source).

Perhaps I don’t need a full system to base my project on. Perhaps I can delegate parts of my system to different libraries, taking care to write accessor classes using the Decorator pattern, giving me the freedom to swap out for different modules if necessary.

An early candidate worth considering is the Huge library, which despite its name is not an overly large and complex codebase, and could be a basis for my user registration/authentication/login functionality.

Posted in
- Dissertation
No Comments

08 Feb

From Requirements to Features

This weekend I finally created the repository for my project (around a week behind some of my peers, but my emphasis has been on clarifying requirements, not jumping into code).

Roughly, I’m following a three-stage requirements-gathering process:

Informal requirements specification, gleaned from my early supervisor meetings.
Cucumber features encompassing all of the above requirements, allowing me to code a corresponding regression test and make the requirements executable.
Agile stories encompassing the above requirements (at times duplicating the Cucumber features), representing units of work that need to be completed in a sprint. I’m hoping to follow the XP-style process of prioritising which stories go into which sprints, by estimating the effort involved for each story and getting the stakeholders to decide on the value presented by each story, and therefore which stories should be tackled first.

The first step is done (requirements can be inferred from my “Clarifying requirements” blog post). From that, I’ve tried to translate a timeline of theoretical events into explicit features that can be signed off and translated into code. There are currently 19 “@TODO” tags (the account_creation.feature file is a good example of this), each of which is a question or ambiguity raised from inadequately detailed requirements.

I’d like to get the questions answered and the feature files signed off by the stakeholders in this project before I write any code. In the meantime, I still need to read the Maritime Law documents fully and examine libraries and frameworks I could use as a basis for my project.

Posted in
- Dissertation
No Comments

06 Feb

Clarifying requirements

Yesterday I had my second Major Project meeting, this time in the presence of Dr Constantina Sampani, a lecturer in Law at Aberystwyth University and, as I understand it, the person who commissioned my project.

This meeting helped to clarify three things:

Requirements of the project, which I’ll delve into in detail later in this post. Credit to Alexandros for typing up much of the content.
Licensing restrictions – I questioned whether or not the project had commercial promise, and, if so, whether or not it should be open source. A commercially viable project should probably be closed source if, as Eric S. Raymond puts it, the “value of the secret bits is more than the peer review return from going open source“. This would have implications such as not being able to use GPL-licensed libraries in my project, as my entire codebase would then come under the GPL license terms. Georgios’s preference was for an open source project, as this reduces my restrictions in terms of which libraries can be used, and argued that responsible code reuse should be actively encouraged.
Copyright restrictions – Following on from my commercial viability question was the question of who “owns” the project. If it were to be come financially attractive, would I be able to claim the project for myself? Constantina suggested that, as a derived work from all four of us, the project would be owned by Aberystwyth University.

Requirements

Definitions

Company Account – an authorised user (e.g. managing director) can register a company on its behalf, creating a Company Account.
Agent – each Company has a list of Agents associated with it. An Agent might be a lawyer, representative, managing director, or legal representative.
Mediation Centre – effectively a collection of Mediators, e.g. The Mediation Centre UK.
Mediator – the third-party individual involved in resolving more complicated disputes later on in the process.
Case – our term for the ‘dispute’.
TTCTC – my own term, standing for ‘Take the Case to Court’. This can happen at many points in the online dispute process, so it is helpful to have it in our vocabulary.

Account registration

An authorised user can create a Company account.
(The Company Account could be subject to some remote checks before being verified).
Company accounts are associated with Agent accounts and are able to create new Agent accounts.

Starting an Online Dispute

Company A creates a Case on behalf of their client.
Company A allocates an Agent to be the legal representative of the Case.
The Agent (from now on referred to as Agent A) reviews the Case, writes a summary of it and submits it to the system. At this point, Agent A is the representative.
Agent A initiates that Case against Company B.
- A notification email is sent to the administrative contact at Company B.
- If the Company has not already registered, they must do so at this point.
- Company B must now log in to continue.
Company B allocates Agent B to represent the Company on this particular Case.
Agent B reviews the Case (and is able to read Agent A’s summary) and writes their summary of the Case to accept it.
Agents A and B must now negotiate the Case lifespan:
- Either Agent can make a time offer (e.g. dispute starts 1st March, 3:00pm, and ends 5th March, 3:00pm).
- The other Agent can either accept the time offer, propose a new time offer, start the Mediation process, or TTCTC.
- Assuming we haven’t TTCTC, this process is repeated until a time has been negotiated.
- At any point in the dispute, either Agent can try to renegotiate the time, thereby starting this process again.
- If the Case is not resolved within the allocated time, automatically TTCTC.

Ambiguities/Interpretations:

These requirements imply that there should be a facility (independent of the current “state” of the Case) to renegotiate the Case lifespan (perhaps a small form in the top-right corner, etc).
An Agent CANNOT create a Case – only the Company can.
An Agent CANNOT assign themselves to a Case – the Company must allocate the Agent.
There is no option to decline the online dispute and TTCTC without registering a Company account.
There is no option for Company B to decline the case – they must allocate Agent B.
There is no option for Agent B to decline the case – they must write a summary, and then must NOT successfully negotiate the Case lifespan. This is the quickest way to TTCTC.

Questions raised:

What happens if Agent A attempts to renegotiate the Case lifespan (after the Case lifespan’s original lifespan negotiation)? Does the case go “on hold”, or continue until the original Case deadline if the renegotiated time is not accepted by Agent B?
If one can start the Mediation process without having finished setting a Case lifespan, what is to stop Mediation from happening indefinitely? Does the Mediator set a default Case lifespan?
If “Either Agent can make a time offer”, how do we handle parallelisation?
- Agent A accesses the “Make a time offer” screen.
- Agent B accesses the “Make a time offer” screen.
- Agent A submits their time offer.
- Agent B attempts to submit their time offer – what should happen?
  - Could be “Error: Agent A has sent you a time offer. Are you sure you want to continue?”
  - Could check Agent A’s offer and Agent B’s offer and if they match, automatically continue, else treat Agent B’s offer as a new offer for Agent A to consider.
How does Company A “know” to initiate the Case against Company B, and not Company C?

The Online Dispute Resolution Process

Now that we have Companies A and B, Agents A and B and a negotiated Case time lifespan, the dispute resolution process can begin.

Agents A and B can communicate freely. At every communication step, the recipient Agent has the following options:

Accept the sender’s offer – dispute successfully resolved.
Send an offer back – continuing the dispute.
Mediation offer – suggest to the other Agent that a Mediator is required.
(As always, either Agent also has the freedom to close the Case unsuccessfully and TTCTC.)

Let’s assume that Agent A goes for the ‘Mediation offer’ option:

Agent B has the freedom to turn down the offer for Mediation, thereby triggering TTCTC.
If Agent B accepts the Mediation offer, the following process is triggered:
- The system offers a list of available Mediation Centres. Agent B selects all Mediation Centres that they find acceptable to work with.
- Agent A selects all Mediation Centres that they find acceptable to work with. Neither Agent knows which Mediation Centres the other selected.
- If no Mediation Centres are selected by both Agents, the process is repeated, a maximum of two times before automatic TTCTC.
- If multiple Mediation Centres are selected by both Agents, the list of common choices is presented to both Agents, and one must be selected.
With the Mediation Centre chosen, the Mediation Centre provides a list of Mediators (including their details, such as CV) to both Agents. The above process is largely repeated, but with Mediators rather than Mediation Centres.
Now we have a mutually chosen Mediator from a mutually chosen Mediation Centre. Whereas before, Agents A and B could communicate freely, now they must only communicate through the Mediator.
A confidentiality agreement is signed at this point.
- There was a suggestion that a fourth person might be required to moderate the Mediator, to ensure that the Mediator is not passing confidential information about Agent A to Agent B.
- There was also the suggestion of self-moderation, such that when the Case is resolved (successfully or otherwise) the full communication records between both Agents and the Mediator are made available to all.
- Finally, there was the suggestion of technological moderation, so that messages between an Agent and the Mediator are automatically scanned for confidential information.

Ambiguities/Interpretations:

These requirements imply that, like with the “Renegotiate Case lifespan” facility, there should be a state-independent option that allows either Agent to close the case unsuccessfully and TTCTC.

Questions raised:

Could the confidentiality agreement be signed upon creation of the Mediator account, rather than on a Case by Case basis?
What happens if the Mediator refuses to sign the confidentiality agreement?
“If multiple Mediation Centres are selected by both Agents, the list of common choices is presented to both Agents, and one must be selected”. How? What is the process for both Agents to narrow down to one Mediation Centre?
If only one Mediation Centre is selected by both Agents, is that Mediation Centre automatically chosen on behalf of the Agents?
What happens when a Case is resolved successfully? What information needs to be made available to both Agents, and how? Is there some sort of overview/summary confirmation, e.g. “Agent A accepts Agent B’s offer of $5,000,000 damages, to be paid within 28 days.”

Mediation and Maritime Collisions

Up until now, we have a general online dispute resolution system. Not all ODS platforms have the above features, but what is being proposed so far does not push the boundaries much over what already exists. However, the Mediation stage is where the Maritime Collision business logic will be applied.

Given the case has not expired and no Agent has terminated the case, keep doing the following:

System offers a form or forms to Agents A and B to attach their evidence material regarding the Case.
All of this information is passed to the Mediator and not made available to the other Agent.
The Mediator reviews and evaluates the evidence material and advises parties individually using 1:1 communication. This is the stage where the maritime collision business logic can be applied. For example, the system can interpret the answers given by both Agents and play out a court simulation suggesting an outcome to the Mediator. The Mediator has the legal expertise to follow or ignore that advice, but it would be a useful second opinion.
- A sufficiently sophisticated business logic module that passes all legal scrutiny could eventually be made available earlier on in the process, before Mediation, to suggest a resolution to the Case to both Agents. We could compare the suggestion of the “virtual Mediator” with the final resolution proposed by the physical Mediator and when these are sufficiently and consistently similar, the inclusion of the virtual Mediator as a pre-Mediation step could be considered.
Agents A and B take some time to consider their next step. Having considered Mediator’s advice, they can either accept the suggested offer (successful resolution) or continue the process.
The Mediator sends both parties an invitation for round table communication. i.e. both Agents can communicate openly in the presence of the Mediator.

Ambiguities/Interpretations:

These requirements suggest a specific form of communications platform:
- Pre-Mediation, Agents A and B communicate with one another freely via a private messaging system (albeit with the freedom to attach documents as evidence, etc). If this is the case, I may use an issue management system such as JIRA as inspiration for my design.
- During Mediation, this private messaging system between Agents A and B becomes “locked” (though messages and evidence attached pre-Mediation should still be visible). Instead, an additional private message “thread” is opened between Agent A and the Mediator, and Agent B and the Mediator.
- In addition to free (as in movement of) messaging between the Agents and the Mediator, there is a structured (i.e. not “free”) form of communication offered to each Agent via the system. This structured communication is:
  - A series of forms, generated by the maritime collisions business logic, requiring discrete answers (“15m”, “true”, etc) rather than freeform text.
  - Upon completion of the forms, the evidence collected by the system is made available to the Mediator. At this stage, the “court simulation” can be carried out, to suggest an outcome to the Mediator.

Questions raised:

I’m not entirely sure how the above few steps can be “iterated”, as was suggested in the meeting. If we go back to step 1, does the round table communication stop and both parties deflect back to communicating via the Mediator, or does it continue into the next iteration of the loop?
What kind of forms (in step 1) can be generated for the Agents in the second (and subsequent) iterations that couldn’t have been generated in the first?
“Agents A and B take some time to consider their next step” – is there a time limit? How do we synchronise the answers of the two Agents?
What happens if either of the Agents refuses round-table communication, but wishes to continue the online dispute through the Mediator? Is this not possible – would the Case automatically TTCTC?

Next steps

As you can gather, even fairly concrete requirements are open to interpretation and raise yet more questions. The steps I hope to accomplish in the next few days are:

Clarifying the requirements further, by answering the questions raised above.
Reading around Maritime Law – though I understand that Constantina will be providing a set of rules the business logic should follow, so makes my reading and interpretation of Maritime Law less important. That said, I’d like to read the Laws – and that also means clarifying from Constantina which set of Laws I should read and apply (my Outline Project Specification links to two versions, one simpler than the other).
Exploring the open source online dispute resolution software solutions available, to see if I can base my project on an existing codebase. I’d like to make a decision on this before the next meeting.

Posted in
- Dissertation
No Comments

03 Feb

Outline Project Specification

Describes my Major Project, the tasks required and the project deliverables.

Posted in
- Dissertation
- Reports
No Comments

31 Jan

Project clarified

Yesterday I met with my supervisor, Georgios Gkoutos, and intermediary law contact, Alexandros Giagkos, in my first Major Project meeting. In that meeting I was able to clarify what my project involves.

If you’ve been following my blog, you may remember that I could interpret my project, Online Dispute Resolution for Maritime Collisions, in one of two ways:

A “court approximator“, taking the details of your maritime collision and comparing with historical cases to predict the outcome of your case.
An online platform allowing communication between two parties in a formalised way, with some specific maritime collision features such as retrieving similar cases and the ability to search other historic cases.

It turns out that what was intended was actually a hybrid of the two systems, in that I’d need to develop an online dispute resolution platform (of which there are many), but tailored specifically to maritime collisions in the types of questions that both parties are required to answer. At the end of a number of stages of questions, results for both parties are displayed, and this step involves the “court simulation” step I’d hoped would be a requirement!

Artist’s impression of the “court simulation”.

This simulation will not deliver a binary yes/no answer as to whether or not one’s case would “win”, but would render a graphical line chart showing the influencing factors (the parties’ responses to questions, similarity to historical cases, etc). Parties could see an approximation of how the court case would play out, the points at which the judge might be in favour or against them, and so on, eventually converging on a final outcome: “Taken to court, it is likely that Party A would win the case.”

Project clarified somewhat, let’s go back a step and examine the requirements in detail…

ODS – An Introduction

When it comes to resolving disputes, many people are increasingly turning to online dispute resolution (ODS) platforms as an alternative to taking the case to court. The latter puts both parties through the expense and inconvenience of having to travel to a physical court, often multiple times. ODS can settle disputes more quickly and cheaply, and arguably provides a clearer and more appropriate means of examining digital evidence.

ODS platforms already exist. They allow lawyers to open disputes on behalf of their clients, upload documents and type content in a structured manner, and hopefully reach an amicable resolution. However, they do not typically perform any processing on the inputted data; there is no business logic that helps influence the outcome. Lawyers are left to examine the viability of both sides of the dispute manually and reach a mutual conclusion, or take the dispute to court.

Online Dispute Resolution for Maritime Collisions

Online Dispute Resolution for Maritime Collisions will attempt to codify that business logic in a very abstract way. Depending on the answers to the first set of questions, the system may deliver a different subset of questions to either party. Upon answering all of the questions, a virtual “court simulation” is played out on the answers and used to approximate a decision of which party is in the right, according to maritime law.

In addition to the court simulation, I’m hoping the system will be able to analyse the details of the case, from the perspectives of both parties, and find and retrieve the most similar historic cases. Done properly, this could even influence the outcome of the decision in the court simulation.

Finally, a brief overview of the dispute may be made available to both parties, with individual comparison details such as “Party A was heading out to sea. Party B contests this.” Some details, such as the level of confidentiality of either party’s answers, need to be clarified in a later meeting. It may be that each party should only be allowed to see the overview of their own answers, not those of the other party.

Iterative Project Plan

From yesterday’s meeting, I’ve identified some incremental requirements:

To build an Online Dispute Resolution platform. This is the minimum viable product, and as has been pointed out, is potentially substantial enough to be a Major Project on its own, encompassing front-end development, back-end business logic and database integration. Having said that, I have been given permission to investigate open source platforms as a starting point, such as Emcod, in which case this stage may not require very much work.
For this Online Dispute Resolution to be tailored to Maritime Collisions, providing some sort of conclusion (I’m using the term “court simulation”) given the details of the dispute. As a worst-case scenario, this may mean hard-coding business logic, rules, database schemas, and so on, to fit with maritime collision properties.
For this Online Dispute Resolution to be an abstraction, able to take a module of business logic (perhaps Maritime Collisions, perhaps something else – hence the abstraction). Georgios stressed the importance of keeping this system abstract, so I will aim to develop straight to this stage, skipping stage 2. An advantage of an abstract system is that we can feed very simple business logic modules to the system, making it easy to test.
As an additional feature, the system should be able to retrieve the most similar historical cases, which should be of use to the lawyers involved. This will likely involve a large degree of setup work, including sourcing the cases and representing them in a consistent data structure.
Following on from the ability to retrieve similar cases is the ability to feed the details of the similar cases into the current dispute, thereby influencing the “court simulation” and making this feature even more accurate and valuable.

I’ll aim to start with requirement 1, following the “You Aren’t Going to Need It” principle and keeping the design simple, but also keeping requirement 3’s abstraction principle at the forefront of my mind. I hope to skip requirement 2 altogether, arriving at it via requirement 3.

Those first few requirements will be substantial enough, but if I have time I’d like to attempt requirements 4 and 5.

Other Requirements

Yesterday’s meeting suggested other, lower-level requirements:

Confidentiality – Alexandros stressed that Party A need not know the company size of Party B, and vice-versa. Both parties have the right to be considered equal. Exactly what is and isn’t allowed to be known to both parties needs to be clarified.
Security – this being a utility for lawyers, they need to be assured that the confidential details of their clients and clients’ disputes remains secure, and that the system is protected against XSS/CSRF/SQL injection attacks.
Parallelisation – both parties should have an equal amount of time to formulate and submit the answers to the questions. There needs to be a fair way for both parties to agree the start and end to the window of time they’re allowed to answer each stage of questions. The system should be fair regardless of lawyer culture. For example, some lawyers follow a linear, question-by-question approach, whereas others might gather together as groups in formal meetings to tackle individual questions over a period of several days.
Testable – the behaviour of the system should be verifiable through a suite of automated tests. At the low level, I hope to write (in whatever language I end up using) in a test-driven way, improving the low-level design of the system while producing a test suite as a by-product. At the higher level, I hope to write Cucumber features that are executable as integration tests, testing features such as logging in, uploading documents, etc. In addition to these tests, the business logic in the court simulation must also be predictable, consistent and testable.

Finally, I have my own considerations that need further discussion:

Copyright – could this project, or a derivative of it, be a commercially viable system? If so, do the rights to the project lie with me, my supervisors, the law contact, or some combination? How will the system be used?
License – regardless of who owns the copyright, is there a restriction on the type of license I should apply to the project? Choosing a GPL license, for example, requires making the source code publicly available, which could be a security risk*, and certainly puts the project at a commercial disadvantage. Following on from this point, I’ll be using GitHub as my version control system: am I allowed to make this a public repository, or will I need to pay for a private repository slot?
Ethics – is there any likelihood that the system could be used by lawyers to examine a client’s case and, seeing that the court simulation is not favourable, deny vulnerable people the legal protection of their choice? I’d be interested to know the plans for the system upon its completion.

Next steps

Now that I’ve clarified the requirements of my project, I can begin to write the Outline Project Specification, which is due on Friday. I look forward to uploading it here as soon as it is ready.

* This is something hotly contested by Eric S. Raymond, author of The Cathedral and the Bazaar, who says that closed source code is “secure by obscurity, rather than secure by design” and suggests that making your project open source can actually make it more secure.

Posted in
- Dissertation
No Comments

04 Feb

Localised CSS

EDIT (6th February, 2015): since publishing this post, I’ve been informed about Element Queries; a W3C discussion about the need for element queries and their required implementation. When I say “Localised CSS”, I was referring to what the world now knows as Element Queries – only I didn’t know it yet. It can be hard to know what to Google in preparation for your blog post! Anyway, I have now contributed my Localised CSS polyfill to the Element Queries group.

For historical note, the original blog post is captured below in its unedited form.

We’ve been doing responsive design all wrong.

I’m not talking about what the end-user sees. If we follow current best practices (mobile-first, progressive-enhancement, unobtrusive JavaScript and the like), mobile users and those reliant on screen-readers have never had it better than they do today.

I’m talking about the way we develop. We’re making lives hard for ourselves, setting ourselves up for challenges we can’t possibly win. We’ve tried to make life easier by using pre-processing tools like SASS, allowing us to use variables in our CSS and split it into logical modules. We use CSS linting tools to spot bugs and duplication before it happens. We try and follow a “mobile-first” development mindset, standardising the approach we take to development, improving consistency in our codebase and lessening the learning curve for other developers joining our projects (as well as providing an efficiency boost when rendering on mobile devices).

Despite all this; robust and elegant responsive designs are very hard to achieve. Why? Because they require the developer to keep a massive, ever-growing mental model of the design in their heads.

Example: imagine a typical WordPress template. Its sidebar contains a widget-like list of the latest articles, represented by a title and thumbnail. Clicking on any of these list items takes the user to the corresponding article page.

Screenshot of WordPress article — **Typical WordPress template, with sidebar showing latest popular posts.**

On a narrow viewport width of say, 300px, the screen is too small to accommodate the sidebar on the side, so the sidebar slots underneath the main content. Within the sidebar, we want the article thumbnail to stretch to the width of the screen (width: 100%) and the article title to slot below it. This is our “mobile” view*.

Our WordPress theme at 300px. Image thumb is at full width, sidebar is below the main content.

Stretch the viewport width to say, 500px, and now the article thumbnail is looking pixelated and taking up too much screen space. We want to set a width of 50% for the thumbnail, and have the items listed horizontally (float: left) so that we have two article thumbnails per line.

At 500px, we decide to half the size of our thumbnails to prevent them from looking pixelated.

Viewing the theme on an even wider viewport, say 800px, means we have enough space for the sidebar to float to the right hand side of the page now. It no longer needs to slot underneath the main content. But, naturally, the sidebar itself is no longer the full width of the screen.

At 800px, the sidebar is now to the right hand side of the main content – and our two-column design is no longer appropriate.

The sidebar is now about 200px wide, but our thumbnails are set at 50% width, so are only taking up a pitiful 100px each – we need to add an additional media query to make the thumbnails 100% width again when the viewport is 800px wide.

So we add an additional media query to make the thumbnails full-width again when we reach 800px.

The resulting CSS might look a bit like this:

.list .list-item {
  display: block;
}
@media only screen (and min-width: 500px) {
  .list .list-item {
    width: 50%;
    float: left;
  }
}
@media only screen (and min-width: 800px) {
  .list .list-item {
    width: 100%;
    float: none;
  }
}

That’s complicated, which is bad enough. But even worse than complicated media queries are unmaintainable media queries.

Let’s say a couple of months down the line, designers decide to change the width at which the sidebar is able to float to the right, from 800px to a new threshold of 900px. If we forget to update the media queries for our article list, anyone coming to the site on a 850px screen will see the sidebar below the main content (i.e. full width of the screen) but with MASSIVE 100%-width thumbnails!

This scenario is just one component of the website. Most websites are made up of dozens of individual components. Think of the world’s largest websites, where different components are developed by different teams. How on earth do they communicate and keep that kind of information up to date?

Wouldn’t it be nice if we could write CSS that responds locally to changes in the size of element containers, rather than globally to changes in the size of the viewport? Instead of a bunch of horrible, complicated media queries which require the developer to maintain a mental model of every breakpoint in their responsive design, we could write simple CSS like this*:

.list .list-item {
  display: block;
}
@media only local (and min-width: 500px) {
  .list .list-item {
    width: 50%;
    float: left;
  }
}

In this proposed solution, we’re instructing the browser to apply a width of 50% and a “float: left” style to the “list-item” class only when the “list” element is a minimum width of 500px. The keyword here is inside the media query, and that word is “local”.

For a proof of concept, I created a GitHub repository: Localised CSS.

Localised CSS - narrow screen — Localised CSS – narrow screen. Both lists are display: block

Here is the working example from the repository. When the viewport is narrow, the list of items is displayed as a block (i.e. each one sits below the previous one).

When the viewport is a bit wider, the “display: inline” comes into effect, and the list items display one after the other in a horizontal line.

Localised CSS - normal screen — Localised CSS – normal screen. Both lists are display: inline

So far, there’s nothing special here – both scenarios can be easily achieved using standard media queries. But let’s make our viewport a little wider…

This screenshot shows our localised CSS working with a wider screen. Now that the screen is sufficiently wide, I’ve made the decision to move the sidebar up alongside the main container, thereby making the sidebar smaller. The really exciting thing here is that both lists are displayed according to the contexts of their containers, NOT the viewport.

The implications of this are massive. By writing localised CSS, we are no longer required to think what the state of the system will be globally when deciding how we should render our element locally. We’re effectively decoupling the responsive design of our components from the responsive design of the system as a whole. We could create truly elegant, reusable, portable components, and fluid, robust, truly responsive overall designs.

Localised CSS is not without its problems, and we face a number of difficulties:

The fact that it’s a JavaScript library means there’ll be a momentary “flash” of unstyled content while the JavaScript is downloading and executing. Also, users with JavaScript disabled will only see the default (mobile**) CSS you supply.
Getting hold of the raw CSS – since we’re using JavaScript, only stylesheets from the website domain can be processed. External stylesheets raise cross-domain issues.
How to write the CSS in the first place (should it be an element nested inside a media query, or a media query nested inside an element? Should both be allowed?)
Parsing the CSS is a fairly complex problem.
How to apply that localised CSS (e.g. if setting ‘style’ attribute directly, we risk overriding any existing style attribute).
How should we re-render efficiently? On each render, the script performs element width calculations. DOM manipulation is expensive.
How can we handle infinite loops? For example, let’s say a child element is set to be 400px wide if its container is less than 300px wide. This naturally makes the container 400px wide, meaning we remove the child’s 400px-wide style on the next render, meaning the container becomes less than 300px wide again, and so on…

If we can overcome these issues and make localised CSS a viable technique, thousands of developer-hours spent on complicated front-end bugs can be saved, amounting to billions of dollars in saved revenue, allowing for accelerated advancement in other key areas of tech, meaning we get time travel machines and water-to-chocolate generators that little bit faster.

My tongue may be somewhat in my cheek, but I genuinely believe a more modular approach to front-end development is a critical step to improving site maintainability.

Are you a front-end developer? This is a call to arms. Fork my Localised-CSS repository, help me overcome these difficulties, and make this dream a reality.

Become a part of the next web development revolution! The world needs localised CSS.

Footnote:
* This CSS isn’t as clear as I’d like it to be. I tried a few things such as setting the container explicitly, i.e. “@media only local and (container: ‘.list’) and (min-width: 300px)”, but the “container” attribute is invalid and means this block of CSS is not delivered correctly via the JavaScript CSSStyleSheet property API.
** I disapprove of the term “mobile” view, since mobiles have such a range of dimensions these days, and the line between “mobile” and “tablet” is definitely blurring. Still, it gets the point across.

Posted in
- CSS
1 Comment

29 Jan

The five-line rule

You’ve probably heard of the five-second rule. If you drop something tasty on the floor, it’s OK to pick it up and eat it provided you pick it up within five seconds of dropping it, since the bacteria won’t spread through your food and spoil it in such a short amount of time.

This is nonsense, of course – food is already riddled with the bacteria of the surface it lands on the moment it touches it, and it’s at your discretion to weigh up the risks of the bacteria, the hassle of retrieving the food, and the tastiness of the food itself (and perhaps other non-functional requirements, such as how hungry you are, whether anyone is watching, whether you have any backup food, etc). Picking an untainted burger off the recently cleaned kitchen floor is fine; scooping a mostly-eaten trifle off the carpet into your hands is probably not.

Anyhow, generally speaking, you’re allowed to pick up food within five seconds of dropping it: the food is still good. In the same way, if I can understand what your file or class is doing by reading the first five lines, it’s probably pretty good code.

Here, the number five is chosen to fit nicely with my metaphor, but depending on the language, you may need to boost this to 10, 15, or 30 lines. I’d expect a Python script to tell me what it’s doing in under five lines (this is perfectly achievable, as a number of Python entries on ProgramInATweet show). A Java class, requiring import statements, attribute declarations and other setup work may require significantly more.

The point is, the file should be written in such a way as to minimise the amount of effort a developer has to expend on finding out its purpose. Like all developers, I’m lazy; if the file is useless to me, I don’t want to have to read any of its contents to come to that conclusion. If I do have to read some of its contents, at least make it a smaller, more achievable task.

Consider this code snippet, taken from the JSHint library:

#!/usr/bin/env node
/*jshint shelljs:true */

"use strict";

var browserify = require("browserify");
var bundle = browserify();
var path = require("path");
var version = require("../package.json").version;
require("shelljs/make");

var distDir = path.join(__dirname, "../dist");
var srcDir = path.join(__dirname, "../src");

if (!test("-e", distDir))
mkdir(distDir);

Read the first five lines. What does it tell you? Do you know what this script is for? Read on another 5 lines. Are you enlightened yet? How about after 15 lines?

Disclaimer: I love JSHint as a pre-processing tool, and this isn’t meant as an attack on their contributors – but it was the first bit of code that I came across while writing this that served as a suitable example of violating the five-line rule. These first few lines of code give me no indication as to what the file is responsible for (to be honest, the rest of the file isn’t much help either).

You could argue that the file is called “build”, and that gives enough of an idea as to the code’s purpose. However, sometimes due to the restrictions of the platform, or the naming conventions of the tech team, the filename itself can’t be very descriptive. Filename aside, WHAT is it building? How should I use it? Should I not use it at all – is it for internal use? When should it be run? What are its inputs and outputs?

A quick scan of the documentation doesn’t answer my questions, but even if there is an answer tucked away somewhere, hiding answers away in remote FAQs is not a developer-friendly solution to the simple question: “what is this file for?”

Sometimes, we can achieve this easily enough in code:

<!--?php &lt;br ?--> $ip = get_user_ip();
if (!not_banned($ip)) {
download_video();
}

Here it’s fairly obvious in just five lines that we have some sort of location-restricted video that the user is trying to download. The script gets the user’s IP address, checks the IP address against a blacklist, and if the video is allowed to be displayed where the user is located, it is downloaded. This procedural code is not perfect, but it is self-documenting, and it tells you what the script is doing. We don’t need to scroll down further and see the implementation of the functions to understand what is happening.

Other platforms, languages or scenarios might require a different solution, e.g. a header comment at the top of the file describing the file contents. I’ve got a fairly good example of this in the Ashton API:

<!--?php &lt;br ?--> // this should run every 10 mins to create a json file with the info, as
// we don't want to have to query linkedin and twitter every time we load the site.
require_once('twitter/twitter.php');
require_once('linkedin/linkedin.php');

Even this isn’t really descriptive enough, but it does give you an indication that this is a script that should be called in a cronjob, it creates information in JSON format and writes it to a file, and it has external dependencies. Without the comment, and without procedural code, I might otherwise have had to read the whole file to reach the same conclusion. If I’m not interested in the contents or creation of the JSON file I can save my time and look elsewhere.

Next time you finish writing a file, try and imagine coming back to it as someone else. Read the first few lines. Do you know what the intention of the file is? If not, add a descriptive comment at the top – or better still, refactor. Remember the five-line rule.

Posted in
- Web
No Comments

27 Jan

Identifying competitors

I may have misunderstood the fundamental concept of my project in my first Dissertation Diary entry: easily done when I’ve been unable to meet with my supervisor and when the assigned project was not on the official list, giving me little more than the title to go on. As a reminder, the title of my project is “Online Dispute Resolution for Maritime Collisions”.

Today I started looking for any services that already do what my project intends to do. Given that 50% of the title is “Online Dispute Resolution”, I tried Googling the phrase to see if my project will be a specialised branch of an existing industry. It looks, perhaps, like this may be the case.

Modria claim to be “The World’s Leading Online Dispute Resolution Experts”, with over 400 million dispute resolutions to their name. They have an “intelligent resolutions platform” divided into four modules: diagnosis, negotiation, mediation and arbitration. It is a business-to-business product: you can buy a Modria Resolution Center and be “up and running in as few as 30 days”.

The advantages of the Modria Resolution Center are:

Reduced legal risk – resolving disputes quickly decreases the chance of lawsuits because your customers feel like they’re being heard.
Lower operating costs – managing disputes online lowers travel expenses.
Increase customer loyalty – fast, fair resolutions = happier customers.
Fast deployment – allegedly, Modria’s modular approach “takes costly customization out of the equation”.

To me, this looks like a specialised version of JIRA: people create ‘dispute tickets’ to help resolve arguments and ambiguities in a structured, documented way. It doesn’t appear to be the ‘judge and jury’ product I was envisaging when I first heard about this project.

What Modria have done is created a framework allowing businesses to resolve disputes with their customers (and with other businesses)… whatever the dispute may be. So what is the value in me creating an online dispute resolution system specifically for maritime collisions? What can be achieved with a more specialised system?

Hopefully my thoughts to date have not been completely fruitless. My dispute resolution system specifically for maritime law could mimic Modria, but with specialised functions such as:

The abilty to feed in details of your case in a structured way, so that:
- The most similar, resolved disputes are automatically displayed for comparison, along with…
- …an approximate percentage of certainty in the likelihood of success or failure of the client’s case in court. This might help to influence the advice the lawyer gives to their client.
The ability to search for historical cases (irrespective of one’s own case) and bring up the details.

I hope to clarify the nature of my project with my supervisor later this week.

Maritime law

Before I started this project, I was informed that maritime law with respect to vessel collisions is relatively short, simple, and thus translatable to code. The Pacific Islands Legal Information Institute (PACLII) link to a number of documents which define conventions, legislations and laws regarding maritime collisions.

A promising document linked to from the page is the Convention for the Unification of Certain Rules of Law with respect to Collisions between Vessels, drafted in Brussels in 1910 and enforced from March 1st, 1913. This convention lists 17 articles, each of which is only a sentence or two in length and describes rules that come into effect should vessels collide. I can already see how some of these articles might be translated into business logic in code.

Regardless of the nature of my project, I’ll need to know maritime law in detail so that I can validate the behaviour of my application. These documents will be a good place to start.

Posted in
- Dissertation
No Comments

26 Jan

And so it begins

Today I start my Major Project; a compulsory part of the BEng Software Engineering course at Aberystwyth University, and our equivalent of the ‘dissertation’ you might write in another department.

Though the bulk of the work is in planning and implementing a major piece of technical effort, there is also the small matter of the 20,000 word accompanying report, which dwarfs most other dissertations. As such, it’s a little frustrating that I can’t really refer to this piece as a dissertation, and have to give a paragraph-sized explanation to make explicit the amount of work a ‘major project’ actually involves. But that aside…

We’ve been advised to keep a diary of our progress throughout the project, which should come in handy when formulating the final report. Hence, here is my diary. I’m looking forward to finding the time to actually write blog posts on my WordPress site, which I’ve neglected in recent months.

Preamble finished, let’s get on to the main meat of the post…

Online Dispute Resolution for Maritime Collisions

My project, titled “Online Dispute Resolution for Maritime Collisions”, will automate the process of estimating the likelihood of success or defeat of a given maritime collision case. It will use machine learning to look at previous maritime collision cases (which will have been pre-fed into the system), compare these cases to the current case, and outline an approximate percentage chance of successful prosecution or defence. It will be an aid for lawyers, giving an overall idea of the complexity of the case without manual and laborious examination. It will also highlight similar cases, which the lawyers can use in forming their cases in court.

This is my understanding of the project as it currently stands, though I have not yet had the chance to meet with my supervisor. I hope to meet with him early this week to clarify my understanding of the project and the expected deliverables.

Outline Project Specification

By February 6th, I need to submit an Outline Project Specification detailing the proposed tasks and project deliverables I expect to complete as part of my project. I will be spending the next few days on this, and it will be somewhat shaped by the supervisor meeting(s) I hope to have this week. However, a preliminary overview:

Proposed Tasks

Get to grips with maritime law. This is supposedly quite a simple, concise law that should be translatable to code. I’ll need to spend time learning the ins and outs of the law so that I can build the software and validate that it is behaving correctly.
Gather historical maritime law cases, in a consistent format. This may be very sizeable, if collections don’t already exist in the public domain. Or it may be quite simple, if my supervisor is able to provide me with cases.
Process historical maritime law cases. I need cases so that they can be fed into the software and used in the machine learning process. This step may require natural language processing, scraping and parsing techniques, etc. I think it’s unlikely that details of the cases will be in a nice, consistent XML format!
Refine a processing algorithm – likely to be the most difficult part of the project. I need to write code that takes case details, compares the details to historical cases, and accurately returns similar cases and an indicator as to the viability of a case’s success in court.
Develop an interface. I expect the above stages to be low-level, passing command-line parameters and calling scripts directly, etc. As this should be online dispute resolution, this indicates the need for a web application, simple enough for untrained users to use, but with enough scope to input all of the intricacies of a legal case. Again, this might be quite sizeable – it may require user registration and authorisation, the ability to view historical legal case PDFs, advanced search capabilities, etc. This is where the scope will need to be carefully controlled, so that the project can stay on track.
Explore the ethical issues raised. My project will give an indication of the legal outcome of a case and highlight related cases that a lawyer could use in presenting their case. This may affect whether or not a lawyer agrees to take on a case in the first place. Do I want to develop something that could one day be a factor in turning away vulnerable people from the legal protection of their choice? Would it be possible for automated resolutions to replace a judge and jury? Could this be less biased than traditional law? It is possible that ethics may form a sizable portion of my major project report. To consider the issues analytically, I will draw upon the ethical lessons learned in CS22310. This may mean that I protect my project with a prohibitive license, drawing on information learned in CS38110. This is something that will need to be discussed with the customer early on in the process.
Explore the commercial viability of the project. This project looks exciting, and genuinely useful. If it presents a viable commercial opportunity, I’ll need to examine how this might be achieved, outline this in my final report, perhaps implement some of the functional requirements of such a commercial system, and also explore the legal and copyright issues that might be raised, given that I am doing work alongside a supervisor and as part of my degree at Aberystwyth University.

Project Deliverables

Choice of server. An online project needs a server. I’m going to need to investigate the possibilities – localhost, Amazon Web Services, Digital Ocean, JavaEE, standalone server, etc – and document a report formalising my conclusions. This can be added to the appendices of my final report.
Choice of processing language for the algorithm. In writing the algorithm that performs the machine learning, I may choose to use a language well suited to data manipulation (such as Python or R), or if it becomes complex enough I may feel that Java or C++ might be more suitable. The algorithm implementation should be separate from the web application, and should be relatively easy to execute even from another language.
Choice of server-side language for the application. Note: this may be different to the choice of processing language for the algorithm. Likely candidates include PHP (most popular), Node (more consistency between back-end and the JavaScript front-end), etc. All three of these deliverables thus far will be in the form of short (2-3 pages) reports that will form some of my appendices.
Choice of build tool. Depends on my choice of algorithm/server-side language. I may use Ant or Mavern if I end up using Java, or Grunt/Gulp if using JavaScript and Node.
Choice of version management system. I’m already strongly leaning towards Git, as this is what I use regularly and am familiar with, but it may be worth writing a report to justify my choice of Git over, say, SVN.
Problem domain specification. Having read and understood what there is to know about maritime law, using historical and current case details as a guide, and working closely with a contact in law, I’ll need to define a set of business rules to be translated into code.
Interface design. I hope to enlist the help of a designer to come up with an attractive website design that is in keeping with the style of the project. I’ll use this design as a guideline in developing the front-end interface.
Stories or features. Currently undecided as to the project process I’ll follow (e.g. Agile, Feature-Driven, etc), but I need to outline some form of requirements. This may be a traditional requirements specification, but it is more likely to be a collection of features and/or stories which break the project up into manageable chunks. I hope to use something like Cucumber to enable BDD and make these features ‘executable’.
Test suites. I will develop in a test-driven way. A by-product of this methodology is that I will have a collection of test suites that serve as living documentation of the code.
Milestone 1: working algorithm. Though it may be tempting to jump ahead and start making a cool website, the website will be nothing without the underlying algorithm that can predict the outcome of cases. I aim to have such an algorithm working before I make any steps to deploy it to a web environment. At this stage, I expect to pass parameters via command line or file, run the algorithm, and see my results. It will take a while to get this far.
Milestone 2: working website. A basic website that has overcome the challenges of deployment. I should be able to automatically deploy the latest version of my codebase to the server of choice, and as a consumer I should be able to access the website, pass in details of my case and view the results, the algorithm having been triggered server-side.
Milestone 3: expanded website. Should look aesthetically pleasing, and may have additional functionality such as advanced search, etc.
Milestone 4: commercial implementation. If the project is deemed to be commercially viable, I’d like to implement some of the requirements of an e-commerce platform; namely user registration, authentication and authorisation, account managements, payment services, etc.
JIRA tickets. I’ll use my own installation of JIRA for project management (managing deadlines, delegating tasks, etc). For code management, including bug fixes, refactoring, and so on, I intend to use GitHub Issues. Both of these systems will provide valuable project history that would be worthy of including in the appendices.
Final report. I hope to have the project completed in plenty of time so that I can concentrate on my final report, which will be complete with many of the above artefacts.