diff --git a/.markdownlint.json b/.markdownlint.json index b7c7efb..c23c962 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -3,6 +3,7 @@ "line-length": false, "fenced-code-language": false, "commands-show-output": false, + "first-line-h1": false, "ul-indent": false, "ol-prefix": { "style": "ordered" diff --git a/03 Architecture.md b/03 Sprint Planning.md similarity index 74% rename from 03 Architecture.md rename to 03 Sprint Planning.md index 51ae861..f1d8332 100644 --- a/03 Architecture.md +++ b/03 Sprint Planning.md @@ -1,76 +1,95 @@ -# Architecture + +# Sprint Planning Each week you will be expected to complete a series of lab activities. You will be required to reflect on these in your assignment so make sure you keep records of what you have done. You should refer to [this week's presentation](https://drive.google.com/open?id=1GUZTf_4yCVUBWiOS3ACQ8ngkEFak7mZy9lzYwDWePq0). -In this worksheet you will be carrying out the initial planning which needs to take place before the first _sprint_ which will be next week. This stage is often referred to as **sprint zero**. +In this worksheet you will be carrying out the initial planning which needs to take place before the first _sprint_ which will be next week. This will allow you to focus next week on the development of good quality code. ## 1 Reviewing the CPD Plan Back in the first lab each member of your team created a **continous professional development** (CPD) plan where they identified the skills they needed to learn before the first sprint. Since the first sprint starts next week its time to review each of the plans. Split into pairs (or groups of 3) and within each group, print out copies of the plans and go through them, checking off any parts that have been completed and agreeing a suitable date (and some resources) to ensure each member of the team is ready for the first sprint. -## 2 High-Level Architecture - -There is a lot of planning to be carried out before you can start development. Using both your _Domain Model_ and _User Story Map_, start to plan the architecture of the product you will be developing. This architecture needs to be [evolutionary](https://www.thoughtworks.com/books/building-evolutionary-architectures) to allow for changes and support the agile development process you will be using. You should evaluate a number of architectural design patterns including: +## 2 Sprint Planning -1. publish-subscribe -2. model-view-controller -3. web apis +As a team: -why is the _n-tier architecture_ poorly suited to agile development approaches? +1. Identify who will be the **Scrum Master** and who will be the **Product Owner**. +2. Ideally with the client present, take the first user story from the top row of your user story map: + 1. The product owner describes it from the user's perspective + 2. Discusses how it can be implemented and work collaboratively on a whiteboard/flipchart to define it's UI until the client/product owner is satisfied/ + 3. Explain the success criteria (how will the team know they have completed the story implementation. +3. Once the client has left: + 1. Break the story into the component tasks and write these on sticky notes. + 2. Use planning poker to estimate how many hours each task will take. + - If the estimated time for a task is longer than 4 hours, consider splitting the task down. + 3. Add them to the left column of your Kanban board. + 4. Finally the _Scrum Master_: + 1. adds up the estimated durations for the tasks on the Kanban board and + 2. draws out a burndown chart: + 1. The X axis should show the days in the sprint. + 2. the Y axis should show the combined duration. + 3. draws a staight line from the top of the Y axis to the end of the X axis to indicate the optimal burn rate. -## 2 Data Storage +### 2.1 The Kanban Board -Analyse the data storage requirements and decide: +For this first sprint, your Kanban board should have 4 columns as shown: -1. What _type_ of database is best suited (relational, document, graph, etc.) -2. What database technology will be used (MySQL, Redis, Mongo, Neo4J, etc.) +``` +╔════════════════╦════════════════╦════════════════╦════════════════╗ +║ To Do ║ Planning ║ Implementation ║ Done ║ +╟────────────────╫────────────────╫────────────────╫────────────────╢ +║ ┌────────┐ ║ ║ ║ ║ +║ │ │ ║ ║ ║ ║ +║ └────────┘ ║ ║ ║ ║ +║ ┌────────┐ ║ ║ ║ ║ +║ │ │ ║ ║ ║ ║ +║ └────────┘ ║ ║ ║ ║ +║ ┌────────┐ ║ ║ ║ ║ +║ │ │ ║ ║ ║ ║ +║ └────────┘ ║ ║ ║ ║ +╚════════════════╩════════════════╩════════════════╩════════════════╝ +``` -## 3 Deciding on the Technology Stack +At the start of the sprint, all tasks should be in the first column. By the end of the sprint, all tasks should be in the last column. -During this module you will be working in a team to develop a sophisticated suite of tools using a variety of different languages and platforms. It is assumed that you already have the required programming skills... +### 2.2 The Burndown Chart -You should now choose ap appropriate technology stack, making sure you understand the key technologies such as Web APIs and MQTT. By this stage your team should have a clear idea as to what needs to be developed, time for an honest team discussion: +Here is an example of a burndown chart showing the line of optimal development. In this example the sprint lasts from Mon to Fri and there are an estimated 40 hours of development. It shows that the optimum burn rate would be 10 hours per day. -1. Are there any skills required to complete the project that need working on? -2. Are there any potential issues with building any parts of the product? -3. Identify the development platform - 1. What will be your primary development language? - 2. What frameworks will your team be using? - 3. Make sure you are comfortable with the mechanics of writing automated tests for your chosen language including testing async code and creating mocks: - 1. [UnitTest](https://docs.python.org/3/library/unittest.html) for Python - 2. [JUnit](http://junit.org) for Java - 3. [Jasmine](http://jasmine.github.io) for JavaScript - 4. Microsoft [Unit Test Framework](https://msdn.microsoft.com/en-us/library/hh598960.aspx) for .NET - 5. XCUnit for Swift +``` + 40 ║* + ║ * + 30 ║ * + ║ * + 20 ║ * + ║ * + 10 ║ * + ║ * + 00 ║ * + ╚══════════════════════════ + M T W T F +``` -Any skills shortage should be added to the **Continuous Professional Development** (CDP) plans for the appropriate team members. +## 3 High-Level Architecture -## 4 Team Organisation +There is a lot of planning to be carried out before you can start development. Using both your _Domain Model_ and _User Story Map_, start to plan the architecture of the product you will be developing. This architecture needs to be [evolutionary](https://www.thoughtworks.com/books/building-evolutionary-architectures) to allow for changes and support the agile development process you will be using. You should evaluate a number of architectural design patterns including: -Now you need to organise your team in preparation for the first sprint which will start next week. Base your discussions on the first sprint identified in the _User Story Map_: +1. publish-subscribe +2. model-view-controller +3. web apis -1. Based on your skills audit, divide the team into different groups to tackle the different tiers in your solution. -2. Each group should map out how they will achieve the first user story, this should include: - 1. The language they will be using and why. - 2. The editor/IDE to be used. +why is the _n-tier architecture_ poorly suited to agile development approaches? -## 5 Technical Preparation +## 4 Data Storage -1. setting up the development workstations: - 1. installing the software needed. - 2. building simple hello-world programs to check development environment is set up. -2. building and configuring any test servers and platforms -3. configuring GitHub: - 1. making sure everyone in the team can log in! - 2. creating a team in the correct organisation on GitHub. - 3. creating enough correctly named private repositories. - 4. adding the team to each of these so everyone has access to all project repositories. +Analyse the data storage requirements and decide: -Before next week you need to make sure the team have all the required skills and have hacked together some code to prove that everything is solveable. +1. What _type_ of database is best suited (relational, document, graph, etc.) +2. What database technology will be used (MySQL, Redis, Mongo, Neo4J, etc.) -## 6 GitLab +## 5 GitLab In previous modules you have been using the GitHub Enterprise repository within the University but there for this one you will be using [GitLab](https://gitlab.com). As part of this week's labs you should configure GitLab for your team so you are ready to start development next week. @@ -107,70 +126,9 @@ Here is a typical `.git/config` file: email = johndoe@gmail.com ``` -## 7 Interacting with Git +## 6 Interacting with Git The main way you should use to work with Git are the _shell commands_ you enter using the _terminal_. Whilst you should be comfortable using these commands you might want to use a more graphical tool for day-to-day Git operations. There are many options however you should investigate: - Code editor Git integration: most modern code editors such as [Visual Studio Code](https://code.visualstudio.com) either come preconfigured with Git integration or it can be added as a plugin. These tools, whilst ideal for basic git work don't have the capability to run the more powerful commands. - Standalone Git tools: whilst there are a lot of these, many (such as the one available from GitHub) are not easy to use and you may cause issues with your repository. One of the ones recommended is [GitKraken](https://www.gitkraken.com) which although has a cost attached is free for academic use. - -## 7 Sprint Planning - -As a team: - -1. Identify who will be the **Scrum Master** and who will be the **Product Owner**. -2. Ideally with the client present, take the first user story from the top row of your user story map: - 1. The product owner describes it from the user's perspective - 2. Discusses how it can be implemented and work collaboratively on a whiteboard/flipchart to define it's UI until the client/product owner is satisfied/ - 3. Explain the success criteria (how will the team know they have completed the story implementation. -3. Once the client has left: - 1. Break the story into the component tasks and write these on sticky notes. - 2. Use planning poker to estimate how many hours each task will take. - - If the estimated time for a task is longer than 4 hours, consider splitting the task down. - 3. Add them to the left column of your Kanban board. - 4. Finally the _Scrum Master_: - 1. adds up the estimated durations for the tasks on the Kanban board and - 2. draws out a burndown chart: - 1. The X axis should show the days in the sprint. - 2. the Y axis should show the combined duration. - 3. draws a staight line from the top of the Y axis to the end of the X axis to indicate the optimal burn rate. - -### 1.1 The Kanban Board - -For this first sprint, your Kanban board should have 4 columns as shown: - -``` -╔════════════════╦════════════════╦════════════════╦════════════════╗ -║ To Do ║ Planning ║ Implementation ║ Done ║ -╟────────────────╫────────────────╫────────────────╫────────────────╢ -║ ┌────────┐ ║ ║ ║ ║ -║ │ │ ║ ║ ║ ║ -║ └────────┘ ║ ║ ║ ║ -║ ┌────────┐ ║ ║ ║ ║ -║ │ │ ║ ║ ║ ║ -║ └────────┘ ║ ║ ║ ║ -║ ┌────────┐ ║ ║ ║ ║ -║ │ │ ║ ║ ║ ║ -║ └────────┘ ║ ║ ║ ║ -╚════════════════╩════════════════╩════════════════╩════════════════╝ -``` - -At the start of the sprint, all tasks should be in the first column. By the end of the sprint, all tasks should be in the last column. - -### 1.2 The Burndown Chart - -Here is an example of a burndown chart showing the line of optimal development. In this example the sprint lasts from Mon to Fri and there are an estimated 40 hours of development. It shows that the optimum burn rate would be 10 hours per day. - -``` - 40 ║* - ║ * - 30 ║ * - ║ * - 20 ║ * - ║ * - 10 ║ * - ║ * - 00 ║ * - ╚══════════════════════════ - M T W T F -``` diff --git a/04 Agile Development.md b/04 Effective Sprints.md similarity index 79% rename from 04 Agile Development.md rename to 04 Effective Sprints.md index aa5e3da..34e8630 100644 --- a/04 Agile Development.md +++ b/04 Effective Sprints.md @@ -5,12 +5,13 @@ Each week you will be expected to complete a series of lab activities. You will You should refer to [this week's presentation](https://drive.google.com/open?id=1nAEwEr7C6VTcRLSTnGqzhDvFzvek8fcKZuNHcjikBBs). -## 2 Conducting the Sprint +## 1 Conducting the Sprint During this first sprint, your development team will need to carry out a **Daily Standup meeting** every morning. Before this meeting, the _Scrum Master_ should: 1. Check the _Kanban board_ is up to date. -1. add up the hours for all the tasks remaining incomplete on the Kanban board and using this to update the _Burndown Chart_. +2. add up the hours for all the tasks remaining incomplete on the Kanban board and using this to update the _Burndown Chart_. + ``` ╔════════════════╦════════════════╦════════════════╦════════════════╗ ║ To Do ║ Planning ║ Implementation ║ Done ║ @@ -25,13 +26,14 @@ During this first sprint, your development team will need to carry out a **Daily ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╚════════════════╩════════════════╩════════════════╩════════════════╝ -From this Kanban board you can see that one of the tasks has been +From this Kanban board you can see that one of the tasks has been completed (and so these hours come off the burndown chart). -One of the tasks has been started but is not yet complete (this stays +One of the tasks has been started but is not yet complete (this stays on the burndown chart) -The last task has not been fully planned out, this task should be a +The last task has not been fully planned out, this task should be a priority until the next daily standup. ``` + ``` 40 ║* ║ * o @@ -57,21 +59,3 @@ During the meeting: If any problems were identified during the standup these will need to be resolved by the appropriate team immediately **after** the daily standup. Make sure the resolution is explained to the _Scrum Master_ before continuing work. Now each team have tasks assigned and will need to implement these before the next daily standup. - -## 3 Review Meeting - -You will be given a date for the review meeting, this will typically be a week after the start of the sprint. During this meeting you will be expected to do a local demo of the software you built during the sprint so make sure you are prepared. - -1. The **Product Owner** reads the user story/storys completed during the sprint. -2. The **Scrum Master** demonstrates the new features to the client. -3. Any bugs identified are added to the Kanban board to be addressed in the next sprint. - -The team then move on to the next _sprint planning meeting_ whilst the client is present. - -## 4 Retrospective - -Each week the development team should meet up (without the client) and ask each member of the team to identify: - -1. What they should continue to do (existing good practice) -2. What they should **start** doing (new good practice) -2. What they should **stop** doing (eliminiate bad practices) diff --git a/05 Code Quality.md b/05 Code Quality.md index 9b65559..325b93f 100644 --- a/05 Code Quality.md +++ b/05 Code Quality.md @@ -1,6 +1,26 @@ # Code Quality +In this worksheet you will be concluding your first sprint and learning about how automated tests can improve the quality of your code. You should refer to the [lecture slides](https://goo.gl/VHD2SH). + +## 1 Review Meeting + +You will be given a date for the review meeting, this will typically be a week after the start of the sprint. During this meeting you will be expected to do a local demo of the software you built during the sprint so make sure you are prepared. + +1. The **Product Owner** reads the user story/storys completed during the sprint. +2. The **Scrum Master** demonstrates the new features to the client. +3. Any bugs identified are added to the Kanban board to be addressed in the next sprint. + +The team then move on to the next _sprint planning meeting_ whilst the client is present. + +## 2 Retrospective + +Each week the development team should meet up (without the client) and ask each member of the team to identify: + +1. What they should continue to do (existing good practice) +2. What they should **start** doing (new good practice) +3. What they should **stop** doing (eliminiate bad practices) + Each week you will be expected to complete a series of lab activities. You will be required to reflect on these in your assignment so make sure you keep records of what you have done. You should refer to [this week's presentation](https://drive.google.com/open?id=1xy3MWh96JUdI8DiAtOUFznA0aEf4FBzp8zbIrPBtTdw). @@ -9,11 +29,11 @@ In this worksheet you will be critically reviewing the code your team have writt To help you complete the labs, there are working examples for different languages in the `exercises/05_code_quality/` directory. -## 1 Non-Functional Requirements +## 3 Non-Functional Requirements Lets start by adding a suite of tests to improve the general code quality. These won't test how well the code solves the user stories. -### 1.1 Linting +### 3.1 Linting It can be tough for development teams to format their code in a consistent way: naming of variables and constants, extra whitespace, irregular indentation, and other “sloppiness” then often leads to actual bugs in the program. @@ -29,7 +49,7 @@ It can be tough for development teams to format their code in a consistent way: Whilst strictly not part of the _linting_ process, if you are using a _compiled language_ a good test is whether each source code file **compiles** correctly! -### 1.2 Code Duplication +### 3.2 Code Duplication The **Don't Repeat Yourself** (DRY) principle states that you should not have duplicate code scattered around your project as it makes it harder to find and fix bugs, but how can you check this? @@ -46,7 +66,7 @@ There are tools for all main programming languages that can flag up duplicate co - are the results more or less useful? 3. As a team, decide on the settings you will be using and make sure they are used consistently for the remainder of the project. -### 1.3 Checking Dependencies +### 3.3 Checking Dependencies Every time you import a library/framework into your project it gets added to the codebase which means it takes longer to run the program and the size of the code increases. For this reason you should not be importing any dependency that you don't use. @@ -64,7 +84,7 @@ In some languages, all dependencies have to be recorded in a configuration file If you are using a language that uses a config file you should run these two additional tests. -### 1.4 Profiling +### 3.4 Profiling Software profiling is a dynamic program analysis that measures, for example, the space (memory) or time complexity of a program, the usage of particular instructions, or the frequency and duration of function calls. @@ -81,20 +101,21 @@ Most mainstream languages include a profiler: - Does it reveal any useful information about your program? 5. Can you use this data to improve your program? -## 2 Functional Requirements +## 4 Functional Requirements Now we have tested a range of _non-functional requirements_ its is time to write some tests to see if we have achieved the _functional requirements_. -### 2.1 Unit Testing +### 4.1 Unit Testing If you have never done unit testing you should take time to complete the [Testing Your Code](https://www.codecademy.com/courses/testing-your-code) exercises on [Codeacademy](https://www.codecademy.com). -#### 2.1.1 Modularising Your Code +#### 4.1.1 Modularising Your Code It is vital that you provide a comprehensive suite of tests for your existing code. but before you can write effective unit tests you need to ensure that your code is split into a number of independent units. Each module: 1. Should not be dependent on any other module you have written (you can have dependencies to third-part modules). 2. Should contain code that shares a similar function. + ``` ╔═════╗ ╔═════╗ ╔═════╗ In this example the code in modules (A), (B) and (C) ║ A ║ ║ B ║ ║ C ║ is not dependent on any of the other modules and so @@ -108,7 +129,7 @@ It is vital that you provide a comprehensive suite of tests for your existing co Take time to tidy up your code ready for the next step. How much of the code can you isolate in code modules and unit test? Ideally all your code (embedded, API and client(s)) needs to be modularised. -#### 2.1.2 Writing Unit Tests +#### 4.1.2 Writing Unit Tests You should now create a separate test suite for each of these code modules. The test suites are written in the same language as the code you are testing. There are unit testing suites available for all mainstream languages, use the examples in the `exercises/05_code_quality/05_unit/` directory to get you started. Whatever language you are testing: @@ -122,14 +143,14 @@ You should now create a separate test suite for each of these code modules. The There are examples of unit tests for multiple languages in the `/exercises/07_unit/` directory on GitHub. -##### 2.1.2.1 Unit Testing Microcontroller Code +##### 4.1.2.1 Unit Testing Microcontroller Code One special case is writing and executing unit test on code that will eventually run on a microcontroller. There are two approaches that you should investigate and reflect on in your report: 1. Arduino _libraries_ are written in standard C++ so, if there are no dependencies on Arduino-specific libraries you can write your unit tests using a standard testing framework. There is more information in the `exercises/05_code_quality/05_unit/cpp/` directory. 2. If you are using _Arduino-specific libaries_ you may need to test your code using an **Atmel emulator**. Again, there is more information in the same directory. -### 2.2 Integration Testing +### 4.2 Integration Testing Although you now have a suite of unit tests for the isolated mode modules/classes, there are some code modules/units/files that are not currently being tested. This could be for one of two reasons: @@ -137,6 +158,7 @@ Although you now have a suite of unit tests for the isolated mode modules/classe 2. They don't contains methods/functions that are _testable_ in that they don't return data (perhaps they send information to the web browser directly or return API data). it is quite possible to write tests for case (1) but, rather than testing the isolated module they are testing whether the module integrates with the rest of the modules (rather like testing the plumbing). We call these **integration tests** and they are written using the same tools as unit tests even though they serve a different purpose. + ``` ┌─────┐ ┌─────┐ ┌─────┐ In this example the code in modules (A), (B) and (C) │ A │ │ B │ │ C │ has already been tested using our *unit tests*. @@ -147,24 +169,25 @@ it is quite possible to write tests for case (1) but, rather than testing the is └───────────→─╢ D ╟─←───────────┘ 3 modules. We therefore write integration tests ╚═════╝ for module (D). ``` -1. Create a testing suite for your integration module(s). These need to be saved in the same directory as your unit tests but add a different prefix, eg: `integration-xxxx.xx` + +1. Create a testing suite for your integration module(s). These need to be saved in the same directory as your unit tests but add a different prefix, eg: `integration-xxxx.xx`. 2. Write a comprehensive suite of tests to make sure the functions from the other modules are working correctly together. -### 2.3 Code Coverage +### 4.3 Code Coverage In the previous two sections you were told to write a _comprehensive suite of tests_, but what is _comprehensive_? Our test suite should check every: function, branch and line of code. To ensure this has been achieved we need to run a code coverage tool that will generate data to indicate how comprehensive our testing suites really are. 1. Using an appropriate _code coverage tool_, generate a coverage report that includes both the unit and integration tests. 2. You will probably have one or more modules that are _untestable_ because they don't return data to test. You should tell the code coverage tool to **ignore** these (but make sure you don't ignore too many!). -2. Use the _code coverage report_ to identify where the gaps are in your test suite and write additional tests until you score 100%. +3. Use the _code coverage report_ to identify where the gaps are in your test suite and write additional tests until you score 100%. -### 2.4 The TAP Protocol +### 4.4 The TAP Protocol Now modify the output of your tests to generate data that follows the _TAP Protocol_. Once you have achieved this, pipe this data into a number of different **reporters** to generate the tests report as a web page and json file. Are there any other reporters that could be useful? -### 2.5 Software Complexity Analysis +### 4.5 Software Complexity Analysis The final step is to generate a report into the relative complexity of different parts of your system using the appropriate software complexity analysis tool for your chosen language. 1. Identify the parts that have a relatively high complexity and find ways to refactor your code to reduce these. -2. Keep a record of the complexity score and use this to identify where changes have increased the complexity of a module. This may indicate poor architecture or code. \ No newline at end of file +2. Keep a record of the complexity score and use this to identify where changes have increased the complexity of a module. This may indicate poor architecture or code. diff --git a/06 Test-Driven Development.md b/06 Test-Driven Development.md index c82902a..629d2d4 100644 --- a/06 Test-Driven Development.md +++ b/06 Test-Driven Development.md @@ -48,6 +48,7 @@ As a team: 4. Move any tasks you didn't complete in the first sprint onto this new board. 5. Add the new tasks for this sprint to the left column of your new Kanban board. 6. Draw up a fresh burndown chart for the current sprint. + ``` ╔════════════════╦════════════════╦════════════════╦════════════════╦════════════════╗ ║ To Do ║ Write Tests ║ Implementation ║ Refactoring ║ Done ║ @@ -62,7 +63,7 @@ As a team: ║ │ │ ║ ║ ║ ║ ║ ║ └────────┘ ║ ║ ║ ║ ║ ╚════════════════╩════════════════╩════════════════╩════════════════╩════════════════╝ -In the example above note that one of the tasks from the previous sprint had been +In the example above note that one of the tasks from the previous sprint had been started but was not completed. It has remained in the implementation stage. The new tasks for the current sprint have been added into the first column. @@ -115,7 +116,7 @@ If the code is not ready for merging you should add a comment and send it back t Your development team will still need to carry out a **Daily Standup meeting** every morning. Before this meeting, the _Scrum Master_ should: 1. Check the _Kanban board_ is up to date. -1. add up the hours for all the tasks remaining incomplete on the Kanban board and using this to update the _Burndown Chart_. +2. add up the hours for all the tasks remaining incomplete on the Kanban board and using this to update the _Burndown Chart_. The Scrum Master needs to make sure everyone is engaged in the process. Adopt the following policy: @@ -167,4 +168,4 @@ Each week the development team should meet up (without the client) and ask each 1. What they should continue to do (existing good practice) 2. What they should **start** doing (new good practice) -2. What they should **stop** doing (eliminiate bad practices) +3. What they should **stop** doing (eliminiate bad practices)