From 8dece7c1c03987a3e41ddb50019c1ef6e077f5eb Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 29 May 2021 22:28:21 +0300 Subject: docs: describe more of what I did Sponsored-by: author --- README.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 105 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fef3cee..43aef68 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,9 @@ This is the work sample for my job application for a developer position for OSO. +This document explains the work I've done and verifies that the code I +wrote works together with the client. + ## Re-statement of problem To clarify the problem for myself, I am re-stating it. This will also @@ -167,6 +170,8 @@ one it has found so far. * The list in the client doesn't change during the computation: items stay in the same order, and are not added, deleted, or changed. +* The client responds truthfully. + # Remarks * Given the list the client has is unordered, O(n) comparisons is the @@ -174,7 +179,7 @@ one it has found so far. algorithms are possible. If list can be ordered, a binary search would be optimal. -# Acceptance criteria +# Acceptance criteria {#acceptnace} ## Find max of a list of one @@ -246,6 +251,105 @@ when I run max-client.py 7 6 5 then answer is 7 ~~~ +# What I did + +## The client + +I modified slightly the `max-client.py` file: + +* it is now an executable Python script, and formatted with Black +* the user can invoke it with a list of numbers, and tell it whether + to ask the server to find the min or the max number + +I made these changes so that I could use it when verifying the +acceptance criteria defined in this document. The original code tested +only two cases, which I found to be inadequate for my purposes. + +The Python code is not entirely to current Python best practices. For +example, it doesn't use type annotations. I have not started using +those yet: at work I've only used old versions of Python that don't +support type annotations, and in my free time, I don't write anything +of significant size in Python anymore. + +## The server + +The server is in `server.py`, and is a Python program using +`bottle.py`. I chose Python, because for something small and simple +like this it's easy. I chose `bottle.py` because it's familiar for me. + +I could have chosen Rust, and probably the `warp` crate for the HTTP +API, but it would have required much more implementation work, and +probably more than is warranted for this exercise. + +The code is a little simplistic in that it doesn't do much in terms of +error handling, logging, or such. At the same time it's overly +complicated, because I wanted to make sure it allows for more than +just the "max" algorithm. "min" is implemented, and the same structure +should be usable for, say, finding the second largest element. More +interesting algorithms would require changes to the messages: if, for +example, one wanted the server to find out if the list is ordered, the +"done" message would need to be able to express the result. + +## The testing + +I have used the [Subplot](https://subplot.liw.fi/) program to verify +that my server works. Subplot documents the acceptance criteria and +how they are verified. That is this document. The section [Acceptance +criteria](#acceptance) documents the acceptance criteria using +_scenarios_ consisting of given/when/then steps. + +Subplot produces two typeset documents (one in HTML, one in PDF), and +a self-standing test program, which can be run to verify the system +under test fulfills the acceptance criteria. To avoid requiring you to +have Subplot installed, the test program is included in the git +repository as `test.py`. You can run it like this: + +~~~sh +$ python3 test.py --log test.log +srcdir /home/liw/pers/oso/work-sample +datadir /tmp/tmpcom39rm7 +scenario: Find max of a list of one + step: given server + step: when I run max-client.py 1 + step: then answer is 1 + cleanup: given server +scenario: Find max of a list of two + step: given server + step: when I run max-client.py 5 5 + step: then answer is 5 + step: when I run max-client.py 5 6 + step: then answer is 6 + step: when I run max-client.py 6 5 + step: then answer is 6 + cleanup: given server +scenario: Find max of a list of three + step: given server + step: when I run max-client.py 5 5 5 + step: then answer is 5 + step: when I run max-client.py 5 5 6 + step: then answer is 6 + step: when I run max-client.py 5 6 5 + step: then answer is 6 + step: when I run max-client.py 6 5 5 + step: then answer is 6 + step: when I run max-client.py 5 6 7 + step: then answer is 7 + step: when I run max-client.py 5 7 6 + step: then answer is 7 + step: when I run max-client.py 6 5 7 + step: then answer is 7 + step: when I run max-client.py 6 7 5 + step: then answer is 7 + step: when I run max-client.py 7 5 6 + step: then answer is 7 + step: when I run max-client.py 7 6 5 + step: then answer is 7 + cleanup: given server +OK, all scenarios finished successfully +$ +~~~ + +I hope that is satisfactory. --- title: "OSO work sample—MAX" -- cgit v1.2.1