Introduction

This appendix describes each of the activities you will be responsible for in developing your software engineering project.

Task Board

An important tool in the Agile development toolkit is the Task (or Kanban) board. This board provides quick visual feedback on what tasks need to be done over the sprint and how they are progressing. Throughout the sprint, tasks are taken from the sprint backlog by a team member, the corresponding programming, testing, and documentation done, moving the task progressively across the board. Traditionally, these boards are bulletin boards and the tasks are represented by index cards pinned to them:

Task Boards for our Class

IN MS Teams, you can create a Planner tab that can be used in a similar fashion. These consists of tasks that are sorted into “buckets”. There are several strategies your team can adopt to make use of this.

One possibility is to create buckets to duplicate the traditional layout of a Kanban board, and create separate Task tabs for each sprint, i.e.:

When adopting this strategy, you will also want a Task tab for “Product Backlog” to contain tasks that have been proposed, but not picked up for a sprint. Tasks can be moved between boards by selecting Move Task from the ellipsis menu.

Then, select the sprint plan to move it to:

However, a modified approach that works well with MS Planner is to create a bucket for the Product Backlog and each Sprint:

Under this approach, you can move tasks from the product backlog to the current sprint by dragging and dropping them. Additionally, use the built-in progress tools to mark the task as “Not Started”, “In Progress”, or “Done”, mirroring the Kanban categories. This will also make the charts for your bucket show progress:

In any case, tasks can (and should) be assigned to team members as they work on them (you can have more than one assigned team member).

Pick a strategy that works for your team - but be sure to use it! The TA will be reviewing your task boards as part of your process fidelity grade.

Daily Stand Up

The daily stand-up is a brief meeting where each team member presents what they are doing. It’s a kind of check-in to make sure the whole team knows what its members are working on. The name “stand up” comes from the common practice of holding this meeting with everyone standing - so that they want to finish the meeting quicker.

Often the stand-up consists of each team member answering three questions:

1. What did you do yesterday?
2. What will you do today?
3. Is anything blocking your progress?

This helps keep the team on-track, as well as identifying any problems that need addressed (note the problems are not typically addressed during the stand-up itself).

Daily Stand-Ups for our Class

Rather than try to hold a traditional stand-up, which is trickly in a school environment, we will use an asynchronous substitute. In your MS Teams Channel, each weekday (and optionally weekend days) you should post your stand-up response. The TA will be reviewing these as part of your process fidelity grade.

If you choose, your team may also hold regular video-based stand-ups; just please also post the text version.

Sprint Meetings

Each sprint starts with a Sprint Planning Meeting, and ends with Sprint Review and Sprint Retrospective meetings. These three meetings Let’s examine the purpose of each in more detail:

Sprint Planning Meeting

The sprint planning meeting includes both the development team and their customers. In this meeting, the tasks to work on for the sprint are decided upon, through a mutual negotiation process. Essentially, the customer shares what is most important to accomplish from their perspective, while the team advocates for what is necessary from their end. From these lists of goals a cohesive set of features should be agreed upon that the team will complete over the next sprint.

Thus, in this meeting:

• The tasks to be developed this sprint are moved from the product backlog into the sprint backlog
• New goals may be identified, which should be added as tasks to the product backlog or sprint backlog, depending on if they will be addressed this sprint

Sprint Review

The sprint review meeting takes place after the sprint ends, and involves both the development team and the customers. In this meeting the development team should present the current software prototype to the customer. This work is either accepted (if it meets expectations) or rejected (indicating the team went off-course) by the customer. In most cases, the sprint will be accepted but will prompt new thoughts and ideas from the customer. This is a chance for the team to collect feedback on their work and potentially move in a new direction.

In this meeting:

• New tasks may be added to the product backlog, reflecting an increased understanding of the project’s needs

Sprint Retrospective

This meeting is for the development team alone. In it they discuss what went well/poorly over the course of the sprint, and decide on any actions they want to take to improve the team’s functioning.

Sprint Meetings for our Class

For the purposes of the class, you should schedule a single Sprint Meeting with your customer every two weeks, at a time that works for both your team and the customer. This meeting should be scheduled via Microsoft Teams, and all meeting participants (customers and team) invited.

This Sprint Meeting will consist of all three meetings discussed above. Once the customers join, you will start with the Sprint Review of the just-finished sprint, and then transition to the Sprint Panning for the upcoming sprint. Once these meetings have concluded, dismiss your customers and continue to the Sprint Retrospective. Obviously, the first Sprint Meeting will only consist of the Sprint Planning portion (as you are starting your first sprint), and your last will not have a Sprint Planning portion (as you have concluded your last sprint).

Meeting Agenda

Before the meeting, you should prepare a meeting agenda. This agenda lays out the purpose and order of topics to be covered in the meeting. A template for a possible agenda is:

Sprint Review [customers and team]
* Review the prototype
* Ask specific questions about the prototype
* Address any concerns the customer has
* Add any needed tasks to the product backlog

Sprint Planning [customers and team]
* Discuss goals for the upcoming sprint
* Identify any new tasks that need added to the backlog
* Select tasks from the product backlog to move to the upcoming sprint backlog
* Break large tasks into smaller, more detailed ones

customers are dismissed

Sprint Retrospective [team]
* Discuss what went well with the prior sprint
* Discuss what whet poorly with the prior sprint
* Identify strategies to help improve your development process

Throughout the meeting, Take meeting notes in teams, starting with posting the Agenda. This will become a permanent record of your meeting you can refer back to during the sprint. This will also be reviewed by the TA as part of your process fidelity grade, so make sure your notes clearly convey what was discussed.

Sprint Release

At the end of each sprint, you should have a completed prototype of your software, implementing all the features you committed to during the sprint. Moreover, those features should be documented and tested (preferably by automated testing tools with full unit and integration tests).

You will need to:

1. Commit all your changes to your repository
2. Create a release tag for the sprint
3. Upload your release URL.

In SCRUM, a sprint either succeeds or fails. A sprint fails when not all the items in the sprint backlog were completed, or when the implementation of those items is lacking in some degree. This includes functional issues, inaccurate documentation, or incomplete test coverage.

To reflect this, we are adapting criterion grading in evaluating sprint releases. A successful sprint earns full points. A failed sprint earns 0 points.

The criteria your sprint release will be evaluated against are the goals you set in your sprint backlog. Each item in the backlog should be complete in the release. Completion means it meets the following standards:

Development Environment

The code should launch in a dev container with no configuration required (though configuraiton may be necessary for full functionality - if this is the case, it should be well-documented in the README)

Code Quality

The code compiles and runs. It does not suffer from unhandled errors. It performs as described in the user documentation.

Coding Style

There is a consistent and understandable coding style employed throughout the code base. Variable names consistent and descriptive of their roles. Indentation used consistently to delineate nested code bodies.

In-Code Documentation

The code includes detailed inline documentation description of each class, method, and function at their point of declaration. When available, an auto-document style used for inline comments. Non-obvious sections of code commented with a description of their purpose. The documentation is legible, grammatically correct, and profanity free.

Licensing

The GitHub/GitLab repository indicates the license used. The full text of the license included with the project code.

Developer Documentation

The documentation sufficient to orient a new programmer to the codebase and describe where the important aspects of the code are located. Programmer documentation include appropriate diagrams to convey code structure and functionality (i.e. Context, Containers, Components, and Code diagrams, Class Diagrams, Database Diagrams, Swimlanes, Use-Case diagrams). The documentation legible, grammatically correct, and profanity free.

Test Suite

The release include an appropriate test suite that performs unit and integration tests on the existing code base. All tests pass. Where an automated test suite is not possible, the release includes a written test plan and documentation of its outcome for the release.

Specification Document

A specification document is one that lays out the purpose and design of your project. It is a common form of documentation to accompany the development of a piece of software. In a waterfall environment, it may be written early in the process and serve as the basis for the design. In an Agile environment, it will also be written early in the process, but treated more as a living document, i.e. one that is frequently revised to keep in-line with the evolving product.

A good structure for a specification is this one, adapted from a University of Kentucky rubric:

Introduction

• Briefly Describe the real-world problem being solved
• Mention the most important program features and constraints
• Describe the purpose, scope, and intended audience of the document.

Project Overview

• Provide background information on the general factors affecting this product and its requirements
• Identify the client, stakeholders, and users of the system
• Provide a complete description of the problem being solved
• Describe the main features of your proposed system
• Mention the most important constraints influencing design decisions

Development and Target Environments

• Describe the physical environment in which your project will be used, including systems with which it will interface
• Describe the hardware and software resources necessary to build and maintain the product

System Model

• Present a high-level view showing the major components of your proposed system and their relationships
• Use text descriptions which can refer to graphical diagrams (i.e. UML) included as figures or presented in the appendices

User Interaction

• Describe the actions of the program from the point of view of the user
• Provide a sufficient level of detail to let tester determine the system satisfies requirements

Functional Requirements

• Describe in clear, unambiguous terms the functional requirements of the system
• Provide sufficient level of detail for testers to determine if these requirements have been met

Nonfunctional Requirements

• Describe the non-functional requirements under which your system must operate
• Provide sufficient level of detail for testers to determine if these requirements have been met

Semester Goals

• Sketch out two versions of your system: a minimum viable product that meets the essential needs of your customers, and an enhanced version that incorporates all desired features

Appendices

• System Diagrams, Entity Relation or Database Diagrams, Use-case diagrams, User Interface Mockups, etc.

Code Reviews

Periodically throughout the semester we will be conducting code reviews. The purpose of a code review is to have a group of developers examine source code to:

• Identify potential bugs
• Improve code quality
• Ensure adherence to coding standards
• Enhance maintainability and readability of the software

Code reviews are a standard industry practice, and like most industry practice, will vary in how they are conducted depending on the workplace. For the purposes of this class, the code review assignments will follow the procedures described below.

1. Code reviews will be conducted by the entire class during the scheduled class day, potentially along with invited faculty and graduate students.
2. We will review the last sprint release tag in the team’s repository.
3. The code review will be conducted in two parts.

Part I

For the first part of the review the development team will not speak, but rather take notes while the rest of the class examines the codebase. A well-written and documented codebase should be relatively easy for new developers to orient themselves to. If it is difficult for the reviewers to make heads or tails of the code, it is an indication that more clarity in the design and documentation is needed, and that maintaining the software will be difficult as-is. During this phase:

• Reviewers will discribe how they understand the program will work based on the code they read.
• Code “smells” will be called out during this process
• Likewise, elegant, well-done code and documentation should be recognized
• Tests will be reviewed side-by-side with the code it is testing. Well-written tests will help explain code functionality.
• Documentation (both inline and external) will likewise be reviewed. I.e. a high-level architectural diagram is the likely starting point for the review.
• Questions may be asked of and answered by the development team - but again the primary goal is sense-making from reading the code, documentation, and tests as-is.

This approach is adapted from design critiques commonly used in architecture and other creative fields, and is intended to help students improve thier design process. It can be uncomfortable to listen to a critique of your work, but do your best to keep an open mind and use the opportunity to see where you can improve.

Part II

For the second part of the review the development team takes over and:

• Asks for any clarification they need from the reviewers
• Can share the reasoning behind design decisions that were questioned
• Can brainstorm with the group for potential solutions to challenges found in the code or that are being encountered in moving forward with development
• Ask for references, code examples, etc. to help implement any needed fixes

The purpose of this phase is to provide the development team with the understanding and tools necessary to address any concerns raised during the review.

Code Review Etiquitte

For many of you, this style of code review represents a new kind of activity you have never engaged in. We want our code reviews to be a positive learning experience, where the development team feels safe sharing their work. Here are some guidelines to follow:

• Comments that are less than courteous and insightful have no place in a code review.
• Don’t offer empty flattery. Describe what you like about the project’s code, tests, documentation, etc., and offer specific examples of its strengths.
• Likewise, share what weaknesses you see in the project. Be as tactful as possible.
• All comments should be constructive, helping the developers improve their project.
• Don’t try to redesign the project for the developers. That is for the developers to do - just point out areas of concern.
• Always use “I” statements.
• Avoid loaded judgment words like “dumb” or “stupid”.
• Never start with a disarming phrase like “I don’t want to be mean, but” or “Not to be a jerk, but”. These automatically put the creator on the defensive, and undermine the positive benefit of your critique.

Remember too, that you will be the developer for an upcoming code review. Treat the development team as you hope they will treat you!