Getting Oriented

# Introduction

## Welcome Message

Hello students, and welcome to CIS 642/643 - Software Engineering Project I & II. This is the two-semester capstone course for the Bachelor of Computer Science at Kansas State University. In this course we will learn about software engineering by engaging in the development of real-world software projects supporting the mission of Kansas State University:

The mission of Kansas State University is to foster excellent teaching, research, and service that develop a highly skilled and educated citizenry necessary to advancing the well-being of Kansas, the nation, and the international community.

My name is Nathan Bean, and I will be your instructor for this course.

# Course Structure

This course is primarily a project-based experiential course, where you will learn about software engineering through engaging in the practices of software development. You will be working in small teams of 3-5 students to develop open-source software to meet the needs of a customer assigned to your team. These customers are primarily drawn from the research, extension, and education communities of Kansas State University, and the software you develop for them may potentially impact the lives of many people.

In addition to the software you will develop, we also have several additional components to the course, including a brief introduction to many common practices of software engineering and the opportunity to meet and speak with alumni actively engaged in industry, to learn about the software engineering practices used in their companies.

## Lectures, Activities, and Quizzes

The first few weeks of CIS 642 focus on learning both the history and processes of software engineering. In covering this material, we will have a series of lectures, followed by discussions and activities implementing these processes during the normal class period. These will lead into some group homework activities you’ll be responsible for as well. Once we shift to the group projects, you’ll be responsible for employing the practices, so you should endeavor to develop a strong understanding of them.

## Guest Speakers

Throughout both semesters, we will have guest speakers - primarily alumni working in industry - who will join us to talk about the software engineering practices employed in their companies. You will be asked to reflect on these talks, and discuss what you have learned from them and how it ties into your own experiences and what you’ve been learning about software engineering. It’s also a great way to learn more about the industry, and how varied the approach to software development can be.

## Software Engineering Projects

However, the bulk of the course will focus on building a software solution to support the needs of your customer. We will engage in an Agile development process based on the SCRUM methodology, which consists of iteratively developing software in two-week sprints. Before each sprint, you will meet with your customer and negotiate what are the most important aspects to focus on, and over the two weeks you will develop those features into your software, along with documentation and testing. At the end of the two weeks, you will present your prototype to your customer to solicit feedback, and begin planning your next sprint.

### Weekly Check-ins

Each week your team will have a brief check-in meeting with the instructor to report your progress and discuss any issues you have encountered. This is also an opportunity to solicit advice or address any questions you might have about your project. These meetings will be held during the class period, and you are required to attend.

### Customer Reviews

Your customers will review your progress, communication skills, respectfulness, and professionalism periodically through the semester. You will be provided with feedback so that you can learn and improve your efforts in this area. This is the practical soft skills that many software developers lack, and which your future employers keep telling us students need to better develop. Hence, you should see this as an opportunity to develop a suite of very necessary, but often overlooked skills. Doing so will make you a far better job candidate, and can provide you with some powerful lived experiences to draw upon in job interviews.

### Peer Reviews

Additionally, you will be asked to review each of your team members each of your peers on 1) their participation in group discussion, 2) helping keep the team focused and on-task, 3) contribution of useful ideas, 4) quality of work done, and 5) quantity of work done. These results will be anonymized and shared back with you so that you can strive to improve yourself as a team member. Also, team members who are not “doing their share” of the work will find that they are penalized based on the scores they receive from their team. Remember that there are almost no opportunities to be a “solo” developer left in the world of software development - you need to develop strong teamwork skills if you want to succeed as a programmer in the modern world.

### Presentations

You will also be charged with presenting your work to a broader audience - in the form of final presentations at the end of each course, as well as presenting to the general public at Open House in the Spring for CIS 643. You will be evaluated for your presentation skills for the various audiences involved (technically sophisticated peers at the end-of-semester and general audiences at Open House).

As an experiential course intended to prepare you for the transition to industry, grading operates a bit differently in this class. We will be employing criterion grading. With criterion grading, your work is either deemed “acceptable” or “unacceptable”. Acceptable work earns a 100%, while unacceptable earns 0%. Note there is no partial credit in criterion grading!

While this may seem harsh at first, it parallels what you can expect on the job. If you regularly turn in “almost-there” work in a professional setting, you can expect to be looking for a new job in short order. Your work must be of acceptable level. Of course, you should strive to do exceptional work rather than just acceptable - so there is a possible 5% bonus on criteria-graded assignments for exceptional work.

Given the use of criterion grading, each Sprint Release must meet all of these requirements:

• Code Quality Code should compile and run, not suffer from unhandled errors, and perform as described in the user documentation.
• Coding Style A consistent and understandable coding style should be employed throughout the code base. Variable names should be consistent and descriptive of their roles. Indentation should be used consistently to delineate nested code bodies.
• In-Code Documentation Code should contain detailed in-line descriptions of each class, property, method, and function at their point of declaration. An auto-document style appropriate to the language should be used for inline comments. Non-obvious sections of code should be commented with a description of their operation and purpose. The documentation should be legible, grammatically correct, and profanity free.
• Licensing Full text of the license should be included in the repository, and each file should contain a copyright statement referring to it.
• Developer Documentation The documentation should be sufficient to orient a new programmer to the codebase and describe where the important aspects of the code are located. The programmer documentation should include diagrams of the code structures and how they interact (i.e. class diagrams, database diagrams, use-case diagrams) where appropriate. The documentation describe how to set up the development, testing, and production environments. The documentation should be legible, grammatically correct, and profanity free.
• User Documentation User documentation may be integrated into the project GUI or provided as a separate document or website. The documentation should give currently correct instructions on how to use the software. It should be written appropriately for the target user’s background. It include screenshots, diagrams, or video to enhance understanding. The documentation should be legible, grammatically correct, and profanity free.
• Test Suite The release should include an appropriate test suite that performs unit and integration tests on the existing code base, and all tests should pass. If an automated test suite is not possible, the release should include a written test plan and documentation of its outcome for the release.

Rather than taking attendance every day, which cuts into our class time, I instead record absences as negative points in the corresponding categories. You can find two assignments in the Absences module:

• Team Meeting Absences will be used to record absences from regular team meetings, i.e. the stand-ups and check-ins. These are held during the class period, so there is no reason to miss them.
• Formal Meeting Absences will be used to record absences from the formal team meetings - i.e. Sprint Planning and Sprint Review meetings. These are the meetings where you present your work and plan future work with your customers so absences here are a big deal. Each absence will deduct points equivalent to a drop of a letter grade in the course.

### Peer and Customer Reviews

Not all assignments are criterion-graded. Specifically, the peer review and customer review assignments are based on a survey given to your team members and customers, respectively. This survey asks them to evaluate you on a scale of 1 to 10 across several categories. Instead of translating directly to a grade, we use the following calculation:

Base score = 100 points
-10 points for each category averaging 6 or 7 points
-20 points for each category averaging 4 or 5 points
-30 points for each category below 3 points


This means that a category score of 8, 9, or 10 is “acceptable” and does not impact your grade. However, a score of 8 does suggest you have room to improve in this category, and should strive to do so. Keep this in mind when you fill out peer reviews for your teammates - you can rate them at an 8 or 9 to indicate that you see room for improvement without hurting their grade.

# Course Textbooks

This course does not have a required print textbook. The resources presented in the modules are also organized into an online textbook that can be accessed here: https://textbooks.cs.ksu.edu/cis642-643. You may find this a useful reference if you prefer a traditional textbook layout. Additionally, since the textbook exists outside of Canvas’ access control, you can continue to utilize it after the course ends.

## O’Riley for Higher Education

As the teams in this course will be engaging in developing software for a variety of platforms and languages, I would recommend that you look to the O’Riley For Higher Education digital library offered through the Kansas State University Library for texts to support your effort. The resources available include electronic editions of thousands of popular textbooks as well as videos and tutorials covering the breadth of computer science and software engineering, along with a focus on current technologies and libraries.

If you were to read any book that comes out of our introductory content and appearing in the O’Riley library, I would highly recommend:

“The Mythical Man-Month: Essays on Software Engineering” probably the most influential book on software engineering practices.

The O’Riley library is a great resource for all your CS coursework. It costs you nothing (technically, your access was paid for by your tuition and fees), so you might as well make use of it!

# Course Software

As each development team’s project may use different technologies and require different development tools, it is difficult to say exactly what software you’ll need ahead of time. However, there are a couple of programs everyone in the course will be using:

### Git and GitHub

We’ll be using Git and either GitHub or the departmental GitLab server for version control of all the team projects. You will want to install Git on your development machine. It can be downloaded from https://git-scm.com/downloads.

### Microsoft Teams

We’ll be coordinating the individual teams, as well as the entire class, using Microsoft Teams. Kansas State University has paid for access to Teams as part of our Office 365 subscription. You can either use the online web app or install a local client; both are free when you log in with your K-State email. Both options are available from https://www.microsoft.com/en-us/microsoft-365/microsoft-teams/group-chat-software

### Microsoft Visio

You will also be asked to create architectural diagrams of your project, i.e. UML class diagrams, database diagrams, etc. Microsoft Visio is one tool you can choose to employ to do this. You can obtain a student copy through Azure Portal; follow the directions on the CS support page: https://support.cs.ksu.edu/CISDocs/wiki/FAQ#MSDNAA.

## Remote Desktop Access

Instead of installing software on your own machine, you may optionally employ department or college machines using remote desktop. To use a remote desktop, you must first install a remote desktop client on your computer. Microsoft supplies a client for most platforms, which you can find links to and information about here.

The remote desktop server is behind a network firewall, so when accessing it from off-campus, you must be using the K-State Virtual Private Network (VPN). It has its own client that also must be installed. You can learn about K-State’s VPN and download the client on K-State’s VPN Page

For remote desktop servers, you can use either those maintained by The Department of Computer Science or the College of Engineering.

# Where to Find Help

As you work on the materials in this course, you may run into questions or problems and need assistance. This section reviews the various types of help available to you in this course.

## Microsoft Teams

First and foremost, anytime you have a questions or need assistance in the course, please post in the course group on Microsoft Teams. It is the best place to go to get help with anything related to this course. Before you post on Teams, take a minute to look around and make sure the question has not already been posted before. It will save everyone quite a bit of time.

The major reason we’ve chosen to use Teams for this course is that many companies have adopted it or a similar system to help drive their own development efforts. Thus, in asking you to adopt it for your team communications, it prepares you for using it effectively in the future. Additionally, it provides the instructors a chance to see where you are in your projects. And since the development teams will all be using the platform already, it makes sense to have a group for the overall class as well.

## Other Resources

Beyond MS Teams, there are a few resources you should be aware of. First, if you have any issues working with K-State Canvas, K-State IT resources, or any other technology related to the delivery of the course, your first source of help is the K-State IT Helpdesk. They can easily be reached via email at helpdesk@ksu.edu. Beyond them, there are many online resources for using Canvas, all of which are linked in the resources section below the video. As a last resort, you may also want to post in MS Teams, but in most cases we may simply redirect you to the K-State helpdesk for assistance.

If you run into issues with either the ‘soft’ skills or the technical content you are asked to tackle in the course, please reach out to the instructors or TA. Each of us has a significant amount of practical industry experience and will happily mentor you, much as you will be mentored by more experienced developers when you start your first job. Please do not keep quiet about your struggles - what we are asking you to do in this course is very different than your prior courses, as there is little instructional support for what you must do.

Of course, as another step you can always exercise your information-gathering skills and use online search tools such as Google to find help for your question. Programming resources such as language and library documentation are going to be an invaluable assistance.

Finally, if you find any errors or omissions in the course content, or have suggestions for additional resources to include in the course, DM the instructors on MS Teams. There are some extra credit points available for helping to improve the course, so be on the lookout for anything that you feel could be changed or improved.

So, in summary, MS Teams should always be your first stop when you have a question or run into a problem. For issues with Canvas or Visual Studio, you are also welcome to refer directly to the resources for those platforms. For questions specifically related to the projects, use MS Teams for sure. For grading questions and errors in the course content or any other issues, please DM the instructors on MS Teams for assistance.

Our goal in this program is to make sure that you have the resources available to you to be successful. Please don’t be afraid to take advantage of them and ask questions whenever you want.

# CIS 642 Syllabus

Syllabi from prior semesters can be accessed here

## CIS 642 - Software Engineering Project I (Fall 2022)

### Instructor Contact Information

• Class Times & Location: MWF 9:30am-11:20am DUF 1092
• Instructor: Nathan Bean (nhbean AT ksu DOT edu)
• Office: DUE 2216
• Phone: (785)483-9264 (Call/Text)
• Website: https://nathanhbean.com
• Office Hours: TBA
• Virtual Office Hours: By appointment via Zoom or MS Teams. Schedule a meeting via email or MS Teams Direct Message.
• Teaching Assistant: Akhil Reddy Dudhipala (akhildudhipala AT ksu DOT edu)
• Office Hours: TBA

### Preferred Methods of Communication:

• Chat: Quick questions via MS Teams are the preferred means of communication.   Questions whose answers may benefit the class I would encourage you to post in the course Team, as this keeps a public history your classmates can review. More personal questions should be direct messaged to me.
• Email: For questions outside of this course, email to nhbean@ksu.edu is preferred.
• Phone/Text: 785-483-9264 Emergencies only! I will do my best to respond as quickly as I can.

### Prerequisites

• CIS 308
• CIS 501

Students may enroll in CIS courses only if they have earned a grade of C or better for each prerequisite to these courses.

### Course Overview

The first semester of a two-semester capstone course. Current practices of software development, requirements, design, prototyping, measures and evaluation. Specification, design, and prototyping of a software system.

## Course Description

You will be creating professional-grade software to tackle a real-world application that will be released as an open-source project to the public. This includes:

• Starting from an existing code base. Very rarely will you have the luxury of starting a real-world project from scratch. Almost always, you’ll have to start from an existing program, framework, or API specification, and adapt it to your customers’ needs. Existing code bases are often poorly or incorrectly documented, under- or completely non-tested, and full of spaghetti code.
• Working as a team. You will very likely never work on a solo project in industry - modern software engineering involves teams of tens if not hundreds of programmers, plus many non-technical contributors as well. Good software development therefore involves tools and strategies to minimize code collisions and endure productive and healthy working relationships.
• Working directly with customers to understand what the software needs to do and how it can be most useful to them. This includes usability design and testing, feature negotiation, and human relations.
• Documenting the software as you develop it in a way that supports future maintenance and feature additions.
• Creating test frameworks or applying validation frameworks to ensure your code does exactly what it is intended to do without any errors.
• Refactoring spaghetti code and poor designs for greater efficiency and maintainability.
• Using prototypes to explore new feature ideas for usability and functionality.
• Employing a staged design, testing, and deployment process to ensure that only the highest-quality, functional, and well-tested code ever appears in front of regular users.

This bulleted list captures the course objectives - by the completion of the course you will need to have demonstrated mastery of each point through developing your software engineering project to earn an A.

## Major Course Topics

• Software Engineering
• Requirements Gathering
• Feature Estimating
• Testing and Verification
• Continuous Deployment
• Waterfall Development Model
• Agile Development Models

## Course Structure

This course is primarily a project course – you will be grouped into teams by the instructor and assigned a specific, real-world software application to develop. Each project also comes with real-world customers who will provide guidance and design priorities, judge usability, negotiate development schedules, and determine how well your software meets their needs. Your projects will be released as open-source projects and hosted on a public Github repository. You should realize that this project will be one of the criteria by which your future employers will judge your suitability, as well as the recommendations of both your instructor and customers.

### Lectures, Readings, Class Discussions, and Activities

While the core focus of this course is learning by doing, carrying out the principles of good software engineering while creating or expanding upon an open-source software project to meet society’s needs, understanding the process begins with studying engineering practices. This will be done through video lectures, assigned readings, class discussions, and other class activities.

### Software Projects

Software projects will cover a wide range of uses as well as base technologies/development languages. The instructor will endeavor to match you to a project in your interest area, but this will not always be possible. In all cases, these are real-world projects that will go on to be used by hundreds or thousands of real-world users. Good design is essential and serves to support both these eventual users and to build your reputation as a software engineer.

Software project development will proceed using an Agile methodology with a two-week iterative development cycle. At the end of each cycle, you will release a tagged prototype version of your software using Git’s tagging functionality. This prototype will be graded for: 1) code quality – focusing on readability, maintainability, and efficiency, 2) documentation – focused on accuracy and coverage, 3) testing/verification processes – focused on depth and correctness of coverage.

You will conduct a stand-up meeting, a sprint review meeting, or a sprint planning meeting (or any combination of the above) during the assigned class period. As such, it is vital to the success of your project that you attend these meetings!

## Development Teams

You will be assigned to a development team of 3-4 students. Each student is expected to contribute to all aspects of the development process. This means that you will not have a documentation guru or a testing guru who only writes documentation or tests. Every member should carry part of the responsibility for writing code, tests, and documentation, as well as working with customers. However, you can divide duties in such a way for a specific design iteration – but by the end of the project each member should have contributed equally in each area.

Every two weeks you will have a formal review and planning meeting with some or all of your customers, at which point they will evaluate your iteration’s prototype for how well it meets their needs. This meeting will be scheduled during the course lab time to facilitate coordination of schedules. It is a mark of respect and professionalism to be on-time, well-prepared, and well groomed for these meetings. Missing a meeting (with the exception of emergency circumstances) will result in an automatic lowering of your grade by a full letter (1 on a 4-point scale). The customers’ evaluations, along with a survey of how well they felt the team interacted with them during the design iteration, will be the basis of your customer relation grade. This grade will be adjusted by the instructors if the team members arrive late, are ill-prepared, appear in inappropriate attire (for these meetings, you should be in business casual).

## Process Fidelity

Each team will also be responsible for making adequate usage of the many tools developed to enhance and expedite the software development process. At a minimum, the development team should be using 1) a code repository to manage the sharing of team code (Git publicly hosted through GitHub or the departmental GitLab server is required) 2) a feature planning and bug tracking system like GitHub or GitLab issues, and 3) a documentation wiki (Use the Github or GitLab built-in Wiki). Each of these is a tool you should be using throughout the development cycle, not simply something you throw data into right before your next meeting. You will be graded on how regularly and effectively you utilize these tools.

In addition, Agile software development utilizes a set of artifacts – physical and visual representations of the project’s goals and progress. These help teams and managers quickly assess what needs to be done on a project and how far along the process is. Your team will also need to make appropriate and regular use of these artifacts, including: 1) velocity chart, and 2) burn-down chart.

This course uses a different approach to grading than you are probably used to, criterion grading. In criterion grading, there is no concept of a ‘partial score’; instead your work is either acceptable (and you earn full points), or unacceptable (and you earn no points). This is reflective of industry practice - if you fail in your job, you will get fired.

Each activity you are tasked with is worth a certain number of points, and the guidelines for what is acceptable will be spelled out in the assignment description, so read them carefully!

In addition, exceptional work may be rewarded with a bonus of 5% of the points set for the assignment.

Grades will be issued on a 4-point scale, with 4=A and 0=F. Grades will be issued for each category according to this breakdown:

Class Participation Lectures, Class Discussions, Class Activities 20%
Software Projects Code Reviews, Documentation, Testing, Functionality 20%
Development Teams Peer Reviews, Meeting Attendance, Project Contributions 20%
Customer Relations Usability of Application, Quality of Interactions, Professionalism 20%
Process Fidelity Regularity of tools, creation and usage, of appropriate charts and metrics 20%

Each category is equally important for your preparation for becoming a software engineer - remember, it isn’t only about writing good code, it’s about making that code useful to society!

## Late Work

Late work is considered unacceptable, and as such will result in no points earned on the assignment. As Seniors you should have developed sufficient time management and planning skills to keep on top of your due dates.

For your sprints, remember that in your sprint planning, you are setting your commitments by what you add to your sprint backlog - don’t overcommit! At the same time, you need to be making enough progress to keep your customer happy while ensuring your software is of sufficient quality and adequately documented and tested.

## Dress Policy

As indicated in the customer relations section, students are expected to wear at a minimum business professional attire for the bi-weekly review and planning meetings with their customers. For other meetings with customers. Career and Employment Services publishes guides to professional and casual attire for men and women on their site ( https://www.k-state.edu/careercenter/students/tell_your_story/attire/dresstoimpress.html). These will be used as the grading rubric within this area, so be sure to familiarize yourself with the expectations!

For obtaining inexpensive business wear options, there are many opportunities available to you:

• CES offers the career closet every Monday-Friday, 8am - 5pm at the Berney Family Welcome center to find gently-used professional wear. Students can typically take up to three articles. Monetary donations will go to the Manhattan Emergency Shelter.
• Several thrift stores in Manhattan carry business professional and casual attire at affordable prices (listed by proximity to campus):
• Salvation Army, 310 Poyntz Avenue
• Goodwill, 421 E. Poyntz Avenue
• Grand Old Trunk, 1304 Pillsbury Drive

## Subject to Change

The details in this document are not set in stone – there may need to be adjustments made throughout the semester. If this occurs, changes will be posted to the K-State online page and emailed to student’s K-State email addresses.

## Standard Syllabus Statements

Kansas State University has an Honor and Integrity System based on personal integrity, which is presumed to be sufficient assurance that, in academic matters, one’s work is performed honestly and without unauthorized assistance. Undergraduate and graduate students, by registration, acknowledge the jurisdiction of the Honor and Integrity System. The policies and procedures of the Honor and Integrity System apply to all full and part-time students enrolled in undergraduate and graduate courses on-campus, off-campus, and via distance learning. A component vital to the Honor and Integrity System is the inclusion of the Honor Pledge which applies to all assignments, examinations, or other course work undertaken by students. The Honor Pledge is implied, whether or not it is stated: “On my honor, as a student, I have neither given nor received unauthorized aid on this academic work.” A grade of XF can result from a breach of academic honesty. The F indicates failure in the course; the X indicates the reason is an Honor Pledge violation.

For this course, a violation of the Honor Pledge will result in sanctions such as a 0 on the assignment or an XF in the course, depending on severity. Actively seeking unauthorized aid, such as posting lab assignments on sites such as Chegg or StackOverflow or asking another person to complete your work, even if unsuccessful, will result in an immediate XF in the course.

We reserve the right to use various platforms that can perform automatic plagiarism detection by tracking changes made to files and comparing submitted projects against other students’ submissions and known solutions. That information may be used to determine if plagiarism has taken place.

### Students with Disabilities

At K-State it is important that every student has access to course content and the means to demonstrate course mastery. Students with disabilities may benefit from services including accommodations provided by the Student Access Center. Disabilities can include physical, learning, executive functions, and mental health. You may register at the Student Access Center or to learn more contact:

### Expectations for Conduct

All student activities in the University, including this course, are governed by the Student Judicial Conduct Code as outlined in the Student Governing Association By Laws, Article V, Section 3, number 2. Students who engage in behavior that disrupts the learning environment may be asked to leave the class.

### Mutual Respect and Inclusion in K-State Teaching & Learning Spaces

At K-State, faculty and staff are committed to creating and maintaining an inclusive and supportive learning environment for students from diverse backgrounds and perspectives. K-State courses, labs, and other virtual and physical learning spaces promote equitable opportunity to learn, participate, contribute, and succeed, regardless of age, race, color, ethnicity, nationality, genetic information, ancestry, disability, socioeconomic status, military or veteran status, immigration status, Indigenous identity, gender identity, gender expression, sexuality, religion, culture, as well as other social identities.

Faculty and staff are committed to promoting equity and believe the success of an inclusive learning environment relies on the participation, support, and understanding of all students. Students are encouraged to share their views and lived experiences as they relate to the course or their course experience, while recognizing they are doing so in a learning environment in which all are expected to engage with respect to honor the rights, safety, and dignity of others in keeping with the K-State Principles of Community.

If you feel uncomfortable because of comments or behavior encountered in this class, you may bring it to the attention of your instructor, advisors, and/or mentors. If you have questions about how to proceed with a confidential process to resolve concerns, please contact the Student Ombudsperson Office. Violations of the student code of conduct can be reported here. If you experience bias or discrimination, it can be reported here.

### Netiquette

Online communication is inherently different than in-person communication. When speaking in person, many times we can take advantage of the context and body language of the person speaking to better understand what the speaker means, not just what is said. This information is not present when communicating online, so we must be much more careful about what we say and how we say it in order to get our meaning across.

Here are a few general rules to help us all communicate online in this course, especially while using tools such as Canvas or Discord:

• Use a clear and meaningful subject line to announce your topic. Subject lines such as “Question” or “Problem” are not helpful. Subjects such as “Logic Question in Project 5, Part 1 in Java” or “Unexpected Exception when Opening Text File in Python” give plenty of information about your topic.
• Use only one topic per message. If you have multiple topics, post multiple messages so each one can be discussed independently.
• Be thorough, concise, and to the point. Ideally, each message should be a page or less.
• Include exact error messages, code snippets, or screenshots, as well as any previous steps taken to fix the problem. It is much easier to solve a problem when the exact error message or screenshot is provided. If we know what you’ve tried so far, we can get to the root cause of the issue more quickly.
• Consider carefully what you write before you post it. Once a message is posted, it becomes part of the permanent record of the course and can easily be found by others.
• If you are lost, don’t know an answer, or don’t understand something, speak up! Email and Canvas both allow you to send a message privately to the instructors, so other students won’t see that you asked a question. Don’t be afraid to ask questions anytime, as you can choose to do so without any fear of being identified by your fellow students.
• Class discussions are confidential. Do not share information from the course with anyone outside of the course without explicit permission.
• Do not quote entire message chains; only include the relevant parts. When replying to a previous message, only quote the relevant lines in your response.
• Do not use all caps. It makes it look like you are shouting. Use appropriate text markup (bold, italics, etc.) to highlight a point if needed.
• No feigning surprise. If someone asks a question, saying things like “I can’t believe you don’t know that!” are not helpful, and only serve to make that person feel bad.
• No “well-actually’s.” If someone makes a statement that is not entirely correct, resist the urge to offer a “well, actually…” correction, especially if it is not relevant to the discussion. If you can help solve their problem, feel free to provide correct information, but don’t post a correction just for the sake of being correct.
• Do not correct someone’s grammar or spelling. Again, it is not helpful, and only serves to make that person feel bad. If there is a genuine mistake that may affect the meaning of the post, please contact the person privately or let the instructors know privately so it can be resolved.
• Avoid subtle -isms and microaggressions. Avoid comments that could make others feel uncomfortable based on their personal identity. See the syllabus section on Diversity and Inclusion above for more information on this topic. If a comment makes you uncomfortable, please contact the instructor.
• Avoid sarcasm, flaming, advertisements, lingo, trolling, doxxing, and other bad online habits. They have no place in an academic environment. Tasteful humor is fine, but sarcasm can be misunderstood.

As a participant in course discussions, you should also strive to honor the diversity of your classmates by adhering to the K-State Principles of Community.

### Face Coverings

Kansas State University strongly encourages, but does not require, that everyone wear masks while indoors on university property, including while attending in-person classes. For additional information and the latest on K-State’s face covering policy, see this page.

### Discrimination, Harassment, and Sexual Harassment

Kansas State University is committed to maintaining academic, housing, and work environments that are free of discrimination, harassment, and sexual harassment. Instructors support the University’s commitment by creating a safe learning environment during this course, free of conduct that would interfere with your academic opportunities. Instructors also have a duty to report any behavior they become aware of that potentially violates the University’s policy prohibiting discrimination, harassment, and sexual harassment ( PPM 3010).

If a student is subjected to discrimination, harassment, or sexual harassment, they are encouraged to make a non-confidential report to the University’s Office for Institutional Equity (OIE) using the online reporting form. Incident disclosure is not required to receive resources at K-State. Reports that include domestic and dating violence, sexual assault, or stalking, should be considered for reporting by the complainant to the Kansas State University Police Department or the Riley County Police Department. Reports made to law enforcement are separate from reports made to OIE. A complainant can choose to report to one or both entities. Confidential support and advocacy can be found with the K-State Center for Advocacy, Response, and Education (CARE). Confidential mental health services can be found with Lafene Counseling and Psychological Services (CAPS). Academic support can be found with the Office of Student Life (OSL). OSL is a non-confidential resource. A comprehensive list of resources is available here. If you have questions about non-confidential and confidential resources, please contact OIE at equity@ksu.edu or (785) 532–6220.

Kansas State University is a community of students, faculty, and staff who work together to discover new knowledge, create new ideas, and share the results of their scholarly inquiry with the wider public. Although new ideas or research results may be controversial or challenge established views, the health and growth of any society requires frank intellectual exchange. Academic freedom protects this type of free exchange and is thus essential to any university’s mission.

Moreover, academic freedom supports collaborative work in the pursuit of truth and the dissemination of knowledge in an environment of inquiry, respectful debate, and professionalism. Academic freedom is not limited to the classroom or to scientific and scholarly research, but extends to the life of the university as well as to larger social and political questions. It is the right and responsibility of the university community to engage with such issues.

### Campus Safety

Kansas State University is committed to providing a safe teaching and learning environment for student and faculty members. In order to enhance your safety in the unlikely case of a campus emergency make sure that you know where and how to quickly exit your classroom and how to follow any emergency directives. To view additional campus emergency information go to the University’s main page, www.k-state.edu, and click on the Emergency Information button, located at the bottom of the page.

### Student Resources

K-State has many resources to help contribute to student success. These resources include accommodations for academics, paying for college, student life, health and safety, and others found at www.k-state.edu/onestop.

Student academic creations are subject to Kansas State University and Kansas Board of Regents Intellectual Property Policies. For courses in which students will be creating intellectual property, the K-State policy can be found at University Handbook, Appendix R: Intellectual Property Policy and Institutional Procedures (part I.E.). These policies address ownership and use of student academic creations.

### Mental Health

Your mental health and good relationships are vital to your overall well-being. Symptoms of mental health issues may include excessive sadness or worry, thoughts of death or self-harm, inability to concentrate, lack of motivation, or substance abuse. Although problems can occur anytime for anyone, you should pay extra attention to your mental health if you are feeling academic or financial stress, discrimination, or have experienced a traumatic event, such as loss of a friend or family member, sexual assault or other physical or emotional abuse.

If you are struggling with these issues, do not wait to seek assistance.

For Kansas State Polytechnic Campus:

### University Excused Absences

K-State has a University Excused Absence policy (Section F62). Class absence(s) will be handled between the instructor and the student unless there are other university offices involved. For university excused absences, instructors shall provide the student the opportunity to make up missed assignments, activities, and/or attendance specific points that contribute to the course grade, unless they decide to excuse those missed assignments from the student’s course grade. Please see the policy for a complete list of university excused absences and how to obtain one. Students are encouraged to contact their instructor regarding their absences.

©2021 The materials in this online course fall under the protection of all intellectual property, copyright and trademark laws of the U.S. The digital materials included here come with the legal permissions and releases of the copyright holders. These course materials should be used for educational purposes only; the contents should not be distributed electronically or otherwise beyond the confines of this online course. The URLs listed here do not suggest endorsement of either the site owners or the contents found at the sites. Likewise, mentioned brands (products and services) do not suggest endorsement. Students own copyright to what they create.

# CIS 643 Syllabus

## CIS 643 - Software Engineering Project II

### Instructor Contact Information

• Instructor: Nathan Bean (nhbean AT ksu DOT edu)
• Office: DUE 2216
• Phone: (785)483-9264 (Call/Text)
• Website: https://nathanhbean.com
• Office Hours: MW 10:30-11:30
• Virtual Office Hours: By appointment via Zoom or MS Teams. Schedule a meeting via email or MS Teams Direct Message.

### Preferred Methods of Communication:

• Chat: Quick questions via Discord is the preferred means of communication.   Questions whose answers may benefit the class I would encourage you to post in the course channel, as this keeps a public history your classmates can review. More personal questions should be direct messaged to me.
• Email: For questions outside of this course, email to nhbean@ksu.edu is preferred.
• Phone/Text: 785-483-9264 Emergencies only! I will do my best to respond as quickly as I can.

### Prerequisites

• CIS 308
• CIS 501

Students may enroll in CIS courses only if they have earned a grade of C or better for each prerequisite to these courses.

### Course Overview

The second semester of a two-semester capstone course. Current practices of software development, requirements, design, prototyping, measures and evaluation. Specification, design, and prototyping of a software system.

## Course Description

You will be creating professional-grade software to tackle a real-world application that will be released as an open-source project to the public. This includes:

• Starting from an existing code base. Very rarely will you have the luxury of starting a real-world project from scratch. Almost always, you’ll have to start from an existing program, framework, or API specification, and adapt it to your customers’ needs. Existing code bases are often poorly or incorrectly documented, under- or completely non-tested, and full of spaghetti code.
• Working as a team. You will very likely never work on a solo project in industry - modern software engineering involves teams of tens if not hundreds of programmers, plus many non-technical contributors as well. Good software development therefore involves tools and strategies to minimize code collisions and endure productive and healthy working relationships.
• Working directly with customers to understand what the software needs to do and how it can be most useful to them. This includes usability design and testing, feature negotiation, and human relations.
• Documenting the software as you develop it in a way that supports future maintenance and feature additions.
• Creating test frameworks or applying validation frameworks to ensure your code does exactly what it is intended to do without any errors.
• Refactoring spaghetti code and poor designs for greater efficiency and maintainability.
• Using prototypes to explore new feature ideas for usability and functionality.
• Employing a staged design, testing, and deployment process to ensure that only the highest-quality, functional, and well-tested code ever appears in front of regular users.

This bulleted list captures the course objectives - by the completion of the course you will need to have demonstrated mastery of each point through developing your software engineering project to earn an A.

## Course Structure

This course is primarily an experiential learning (i.e. project-centric) course – you will be grouped into teams by the instructor and assigned a specific, real-world software application to develop. Each project also comes with real-world customers who will provide guidance and design priorities, judge usability, negotiate development schedules, and determine how well your software meets their needs. Your projects will be released as open-source projects and hosted on a public Github repository. You should realize that this project will be one of the criteria by which your future employers will judge your suitability, as well as the recommendations of both your instructor and customers.

### Software Projects

Software projects will cover a wide range of uses as well as base technologies/development languages. The instructor will endeavor to match you to a project in your interest area, but this will not always be possible. In all cases, these are real-world projects that will go on to be used by hundreds or thousands of real-world users. Good design is essential and serves to support both these eventual users and to build your reputation as a software engineer.

Software project development will proceed using an Agile methodology with a two-week iterative development cycle. At the end of each cycle, you will release a tagged prototype version of your software using Git’s tagging functionality. This prototype will be graded for: 1) code quality – focusing on readability, maintainability, and efficiency, 2) documentation – focused on accuracy and coverage, 3) testing/verification processes – focused on depth and correctness of coverage.

You will conduct a stand-up meeting, a sprint review meeting, or a sprint planning meeting (or any combination of the above) during the assigned class period. As such, it is vital to the success of your project that you attend these meetings!

## Development Teams

You will be assigned to a development team of 3-4 students. Each student is expected to contribute to all aspects of the development process. This means that you will not have a documentation guru or a testing guru who only writes documentation or tests. Every member should carry part of the responsibility for writing code, tests, and documentation, as well as working with customers. However, you can divide duties in such a way for a specific design iteration – but by the end of the project each member should have contributed equally in each area.

Every two weeks you will have a formal review and planning meeting with some or all of your customers, at which point they will evaluate your iteration’s prototype for how well it meets their needs. This meeting will be scheduled during the course lab time to facilitate coordination of schedules. It is a mark of respect and professionalism to be on-time, well-prepared, and well groomed for these meetings. Missing a meeting (with the exception of emergency circumstances) will result in an automatic lowering of your grade by a full letter (1 on a 4-point scale). The customers’ evaluations, along with a survey of how well they felt the team interacted with them during the design iteration, will be the basis of your customer relation grade. This grade will be adjusted by the instructors if the team members arrive late, are ill-prepared, appear in inappropriate attire (for these meetings, you should be in business casual).

## Process Fidelity

Each team will also be responsible for making adequate usage of the many tools developed to enhance and expedite the software development process. At a minimum, the development team should be using 1) a code repository to manage the sharing of team code (Git publicly hosted through GitHub or the departmental GitLab server is required) 2) a feature planning and bug tracking system like GitHub or GitLab issues, and 3) a documentation wiki (Use the Github or GitLab built-in Wiki). Each of these is a tool you should be using throughout the development cycle, not simply something you throw data into right before your next meeting. You will be graded on how regularly and effectively you utilize these tools.

In addition, Agile software development utilizes a set of artifacts – physical and visual representations of the project’s goals and progress. These help teams and managers quickly assess what needs to be done on a project and how far along the process is. Your team will also need to make appropriate and regular use of these artifacts, including: 1) velocity chart, and 2) burn-down chart.

This course uses a different approach to grading than you are probably used to, criterion grading. In criterion grading, there is no concept of a ‘partial score’; instead your work is either acceptable (and you earn full points), or unacceptable (and you earn no points). This is reflective of industry practice - if you fail in your job, you will get fired.

Each activity you are tasked with is worth a certain number of points, and the guidelines for what is acceptable will be spelled out in the assignment description, so read them carefully!

In addition, exceptional work may be rewarded with a bonus of 5% of the points set for the assignment.

Grades will be issued on a 4-point scale, with 4=A and 0=F. Grades will be issued for each category according to this breakdown:

Class Participation Lectures, Class Discussions, Class Activities, Presentations 20%
Software Projects Code Reviews, Documentation, Testing, Functionality 20%
Development Teams Peer Reviews, Meeting Attendance, Project Contributions 20%
Customer Relations Usability of Application, Quality of Interactions, Professionalism 20%
Process Fidelity Regularity of tools, creation and usage, of appropriate charts and metrics 20%

Each category is equally important for your preparation for becoming a software engineer - remember, it isn’t only about writing good code, it’s about making that code useful to society!

## Late Work

Late work is considered unacceptable, and as such will result in no points earned on the assignment. As Seniors you should have developed sufficient time management and planning skills to keep on top of your due dates.

For your sprints, remember that in your sprint planning, you are setting your commitments by what you add to your sprint backlog - don’t overcommit! At the same time, you need to be making enough progress to keep your customer happy while ensuring your software is of sufficient quality and adequately documented and tested.

## Dress Policy

As indicated in the customer relations section, students are expected to wear at a minimum business casual attire for the bi-weekly review and planning meetings with their customers. For other meetings with customers. Career and Employment Services publishes guides to professional and casual attire for men and women on their site ( http://www.k-state.edu/ces/students/dresstoimpress.html). These will be used as the grading rubric within this area, so be sure to familiarize yourself with the expectations!

For obtaining inexpensive business formal and casual wear options, there are many opportunities available to you:

• CES offers the career closet every Monday-Friday, 8am - 5pm at the Berney Family Welcome center to find gently-used professional wear. Students can typically take up to three articles. Monetary donations will go to the Manhattan Emergency Shelter.
• Several thrift stores in Manhattan carry business professional and casual attire at affordable prices (listed by proximity to campus):
• Salvation Army, 310 Poyntz Avenue
• Goodwill, 421 E. Poyntz Avenue
• Grand Old Trunk, 1304 Pillsbury Drive

## Subject to Change

The details in this document are not set in stone – there may need to be adjustments made throughout the semester. If this occurs, changes will be posted to the K-State online page and emailed to student’s K-State email addresses.

## Standard Syllabus Statements

Kansas State University has an Honor and Integrity System based on personal integrity, which is presumed to be sufficient assurance that, in academic matters, one’s work is performed honestly and without unauthorized assistance. Undergraduate and graduate students, by registration, acknowledge the jurisdiction of the Honor and Integrity System. The policies and procedures of the Honor and Integrity System apply to all full and part-time students enrolled in undergraduate and graduate courses on-campus, off-campus, and via distance learning. A component vital to the Honor and Integrity System is the inclusion of the Honor Pledge which applies to all assignments, examinations, or other course work undertaken by students. The Honor Pledge is implied, whether or not it is stated: “On my honor, as a student, I have neither given nor received unauthorized aid on this academic work.” A grade of XF can result from a breach of academic honesty. The F indicates failure in the course; the X indicates the reason is an Honor Pledge violation.

For this course, a violation of the Honor Pledge will result in sanctions such as a 0 on the assignment or an XF in the course, depending on severity. Actively seeking unauthorized aid, such as posting lab assignments on sites such as Chegg or StackOverflow or asking another person to complete your work, even if unsuccessful, will result in an immediate XF in the course.

We reserve the right to use various platforms that can perform automatic plagiarism detection by tracking changes made to files and comparing submitted projects against other students’ submissions and known solutions. That information may be used to determine if plagiarism has taken place.

### Students with Disabilities

At K-State it is important that every student has access to course content and the means to demonstrate course mastery. Students with disabilities may benefit from services including accommodations provided by the Student Access Center. Disabilities can include physical, learning, executive functions, and mental health. You may register at the Student Access Center or to learn more contact:

### Expectations for Conduct

All student activities in the University, including this course, are governed by the Student Judicial Conduct Code as outlined in the Student Governing Association By Laws, Article V, Section 3, number 2. Students who engage in behavior that disrupts the learning environment may be asked to leave the class.

### Mutual Respect and Inclusion in K-State Teaching & Learning Spaces

At K-State, faculty and staff are committed to creating and maintaining an inclusive and supportive learning environment for students from diverse backgrounds and perspectives. K-State courses, labs, and other virtual and physical learning spaces promote equitable opportunity to learn, participate, contribute, and succeed, regardless of age, race, color, ethnicity, nationality, genetic information, ancestry, disability, socioeconomic status, military or veteran status, immigration status, Indigenous identity, gender identity, gender expression, sexuality, religion, culture, as well as other social identities.

Faculty and staff are committed to promoting equity and believe the success of an inclusive learning environment relies on the participation, support, and understanding of all students. Students are encouraged to share their views and lived experiences as they relate to the course or their course experience, while recognizing they are doing so in a learning environment in which all are expected to engage with respect to honor the rights, safety, and dignity of others in keeping with the K-State Principles of Community.

If you feel uncomfortable because of comments or behavior encountered in this class, you may bring it to the attention of your instructor, advisors, and/or mentors. If you have questions about how to proceed with a confidential process to resolve concerns, please contact the Student Ombudsperson Office. Violations of the student code of conduct can be reported here. If you experience bias or discrimination, it can be reported here.

### Netiquette

Online communication is inherently different than in-person communication. When speaking in person, many times we can take advantage of the context and body language of the person speaking to better understand what the speaker means, not just what is said. This information is not present when communicating online, so we must be much more careful about what we say and how we say it in order to get our meaning across.

Here are a few general rules to help us all communicate online in this course, especially while using tools such as Canvas or Discord:

• Use a clear and meaningful subject line to announce your topic. Subject lines such as “Question” or “Problem” are not helpful. Subjects such as “Logic Question in Project 5, Part 1 in Java” or “Unexpected Exception when Opening Text File in Python” give plenty of information about your topic.
• Use only one topic per message. If you have multiple topics, post multiple messages so each one can be discussed independently.
• Be thorough, concise, and to the point. Ideally, each message should be a page or less.
• Include exact error messages, code snippets, or screenshots, as well as any previous steps taken to fix the problem. It is much easier to solve a problem when the exact error message or screenshot is provided. If we know what you’ve tried so far, we can get to the root cause of the issue more quickly.
• Consider carefully what you write before you post it. Once a message is posted, it becomes part of the permanent record of the course and can easily be found by others.
• If you are lost, don’t know an answer, or don’t understand something, speak up! Email and Canvas both allow you to send a message privately to the instructors, so other students won’t see that you asked a question. Don’t be afraid to ask questions anytime, as you can choose to do so without any fear of being identified by your fellow students.
• Class discussions are confidential. Do not share information from the course with anyone outside of the course without explicit permission.
• Do not quote entire message chains; only include the relevant parts. When replying to a previous message, only quote the relevant lines in your response.
• Do not use all caps. It makes it look like you are shouting. Use appropriate text markup (bold, italics, etc.) to highlight a point if needed.
• No feigning surprise. If someone asks a question, saying things like “I can’t believe you don’t know that!” are not helpful, and only serve to make that person feel bad.
• No “well-actually’s.” If someone makes a statement that is not entirely correct, resist the urge to offer a “well, actually…” correction, especially if it is not relevant to the discussion. If you can help solve their problem, feel free to provide correct information, but don’t post a correction just for the sake of being correct.
• Do not correct someone’s grammar or spelling. Again, it is not helpful, and only serves to make that person feel bad. If there is a genuine mistake that may affect the meaning of the post, please contact the person privately or let the instructors know privately so it can be resolved.
• Avoid subtle -isms and microaggressions. Avoid comments that could make others feel uncomfortable based on their personal identity. See the syllabus section on Diversity and Inclusion above for more information on this topic. If a comment makes you uncomfortable, please contact the instructor.
• Avoid sarcasm, flaming, advertisements, lingo, trolling, doxxing, and other bad online habits. They have no place in an academic environment. Tasteful humor is fine, but sarcasm can be misunderstood.

As a participant in course discussions, you should also strive to honor the diversity of your classmates by adhering to the K-State Principles of Community.

### Face Coverings

Kansas State University strongly encourages, but does not require, that everyone wear masks while indoors on university property, including while attending in-person classes. For additional information and the latest on K-State’s face covering policy, see this page.

### Discrimination, Harassment, and Sexual Harassment

Kansas State University is committed to maintaining academic, housing, and work environments that are free of discrimination, harassment, and sexual harassment. Instructors support the University’s commitment by creating a safe learning environment during this course, free of conduct that would interfere with your academic opportunities. Instructors also have a duty to report any behavior they become aware of that potentially violates the University’s policy prohibiting discrimination, harassment, and sexual harassment ( PPM 3010).

If a student is subjected to discrimination, harassment, or sexual harassment, they are encouraged to make a non-confidential report to the University’s Office for Institutional Equity (OIE) using the online reporting form. Incident disclosure is not required to receive resources at K-State. Reports that include domestic and dating violence, sexual assault, or stalking, should be considered for reporting by the complainant to the Kansas State University Police Department or the Riley County Police Department. Reports made to law enforcement are separate from reports made to OIE. A complainant can choose to report to one or both entities. Confidential support and advocacy can be found with the K-State Center for Advocacy, Response, and Education (CARE). Confidential mental health services can be found with Lafene Counseling and Psychological Services (CAPS). Academic support can be found with the Office of Student Life (OSL). OSL is a non-confidential resource. A comprehensive list of resources is available here. If you have questions about non-confidential and confidential resources, please contact OIE at equity@ksu.edu or (785) 532–6220.

Kansas State University is a community of students, faculty, and staff who work together to discover new knowledge, create new ideas, and share the results of their scholarly inquiry with the wider public. Although new ideas or research results may be controversial or challenge established views, the health and growth of any society requires frank intellectual exchange. Academic freedom protects this type of free exchange and is thus essential to any university’s mission.

Moreover, academic freedom supports collaborative work in the pursuit of truth and the dissemination of knowledge in an environment of inquiry, respectful debate, and professionalism. Academic freedom is not limited to the classroom or to scientific and scholarly research, but extends to the life of the university as well as to larger social and political questions. It is the right and responsibility of the university community to engage with such issues.

### Campus Safety

Kansas State University is committed to providing a safe teaching and learning environment for student and faculty members. In order to enhance your safety in the unlikely case of a campus emergency make sure that you know where and how to quickly exit your classroom and how to follow any emergency directives. To view additional campus emergency information go to the University’s main page, www.k-state.edu, and click on the Emergency Information button, located at the bottom of the page.

### Student Resources

K-State has many resources to help contribute to student success. These resources include accommodations for academics, paying for college, student life, health and safety, and others found at www.k-state.edu/onestop.

Student academic creations are subject to Kansas State University and Kansas Board of Regents Intellectual Property Policies. For courses in which students will be creating intellectual property, the K-State policy can be found at University Handbook, Appendix R: Intellectual Property Policy and Institutional Procedures (part I.E.). These policies address ownership and use of student academic creations.

### Mental Health

Your mental health and good relationships are vital to your overall well-being. Symptoms of mental health issues may include excessive sadness or worry, thoughts of death or self-harm, inability to concentrate, lack of motivation, or substance abuse. Although problems can occur anytime for anyone, you should pay extra attention to your mental health if you are feeling academic or financial stress, discrimination, or have experienced a traumatic event, such as loss of a friend or family member, sexual assault or other physical or emotional abuse.

If you are struggling with these issues, do not wait to seek assistance.

For Kansas State Polytechnic Campus:

### University Excused Absences

K-State has a University Excused Absence policy (Section F62). Class absence(s) will be handled between the instructor and the student unless there are other university offices involved. For university excused absences, instructors shall provide the student the opportunity to make up missed assignments, activities, and/or attendance specific points that contribute to the course grade, unless they decide to excuse those missed assignments from the student’s course grade. Please see the policy for a complete list of university excused absences and how to obtain one. Students are encouraged to contact their instructor regarding their absences.

©2021 The materials in this online course fall under the protection of all intellectual property, copyright and trademark laws of the U.S. The digital materials included here come with the legal permissions and releases of the copyright holders. These course materials should be used for educational purposes only; the contents should not be distributed electronically or otherwise beyond the confines of this online course. The URLs listed here do not suggest endorsement of either the site owners or the contents found at the sites. Likewise, mentioned brands (products and services) do not suggest endorsement. Students own copyright to what they create.

# CIS 642 Schedule

Week Day Before Class In Class
1 1 Read the syllabus and complete the quiz Course expectations, Introductions, and Team Formation Survey
3 Read about the Waterfall Model of Software Engineering Requirements Gathering Exercise
2 4 Review UML, Design Patterns Software Design Exercise
5 Review documentation and testing Development Exercise
6 Read verification and maintenance sections Maintenance exercise
8
9
4 Sprint 1
5
6 Sprint 2
7
8 Sprint 3
9
10 Sprint 4
11
12 Sprint 5
13
14 Sprint 6
15
16 Final Presentations

# The History of Software Development

“When we started off we didn’t know how to spell software” - Steve Jobs

# Introduction

Since we’ve had computers, we’ve had programs running on them. But what these programs look like, as well as how they are written, has changed drastically over the short period we’ve had electronic digital computers. It can be helpful to review this evolution before we delve into software engineering as a discipline, because this storied history has an immense impact on how software is created.

## Key Terms

Some key terms to learn in this chapter are:

• Software Engineering
• Structured
• Object-Oriented
• Functional
• Logic
• The Software Crisis

# Early Programming

You probably remember seeing pictures of the room-sized ENIAC, the first digial computer constructed in the United States, in CIS 115. But do you remember how it was programmed?

That’s actually what these two women - Gloria Ruth Gordon Bolotsky and Esther Gertson - are doing in the picture. They are programming the ENIAC by plugging jumper cables into a switchboard. Effectively, programming the ENIAC consisted of physically rewiring the computer to support the new program. To make matters even more challenging, the women who developed the ENIAC’s programs were not initially allowed to see the machine due to wartime secrecy concerns. Instead, they had to develop their programs from studying schematics of the computer, and technicians would attempt to recreate the programs they wrote.1

This laborious rewiring process was eventually replaced with stored programs, programs stored in the computer’s memory. The concept was first introduced by Alan Turing in his Universal Turing Machine. In his original conception of Turing Machine, input to the computer was stored on an infinitely long paper tape, and output was written to the same tape - both in the forms of ones and zeros. The program was hard-wired into the head of the machine. Turing had an epiphany when he realized that he could represent instructions to the machine with binary numbers, and then a program using those instructions could also be stored on the paper tape.

These ideas were incorporated into electronic computers by several computer scientists, including J. Presper Eckert and John Mauchly, inventors of the ENIAC, as well as John Von Neumann, who was first to publish such an architecture in his paper “First Draft of a Report on the EDVAC”. For this reason, a computer architecture allowing for stored programs is commonly referred to as a von Neumann architecture, and this is the basis of modern digital computers.

Stored programs also allowed us to develop bootstrap code - libraries of common procedures that could be re-used for future programs, and were loaded into the computer as it was warmed up. This was an important predecessor to modern programming libraries and operating systems.

The next major innovation in software design was the development of programming languages and the associated technologies of compilers and interpreters that allowed programmers to write programs in a higher-level programming language that would then be translated into a machine language for a stored-program computer. Pictured is Grace Hopper, the creator of the first programming language, FLOW-MATIC and influential co-creator of COBOL.

The development of programming languages is especially important in that it allowed us to develop abstractions simplifying development of software and allowing us to express significantly more complex ideas in computer code.

1. Frank da Cruz, “Programming the ENIAC”, Columbia University Computing History, 2020. ↩︎

# Software Engineering

The Apollo missions were marked for their heavy use of computers. For example, this next picture is the memory core of an Apollo Guidance Computer, developed for the Apollo missions. The two hands you see in the picture belong to professional weavers who were hired to implement the program for the mission. The program was encoded using core rope memory, a kind of read-only memory that stored 0 and 1 values by the inclusion or omission of a wire through a series of tiny magnetic rings. Each computer program was truly hard-coded - any mistake would entail a costly rebuilding of the core. 1

Thus, there was significant pressure on NASA to make sure programs were correct. This next picture is Margaret Hamilton, one of the software developers who led the effort to create those guidance programs. She insisted a rigorous approach and comprehensive testing was crucial to the success of Apollo. And her approach paid off - No software bugs were ever found in the Apollo guidance software, and it was later adopted for use with the space station Skylab. The term “Software Engineering” was coined by her to describe her work. And just to emphasize the size of that task - that stack of documents next to her is the source code for the Apollo guidance software! 2.

Unfortunately, not all software was being built to NASA’s exacting standards. At the 1968 NATO Software Engineering Conference, the same year of the first manned Apollo mission, the term “Software Crisis” was coined to describe a growing problem in the software industry.

# Growth of Computing

The unfolding software crisis was coupled to the growth of computing. As Edsger Dijkstra put it in his 1972 ACM Turing Award acceptance speech: 1

The major cause of the software crisis is that the machines have become several orders of magnitude more powerful! To put it quite bluntly: as long as there were no machines, programming was no problem at all; when we had a few weak computers, programming became a mild problem, and now we have gigantic computers, programming has become an equally gigantic problem.

This increase in computing power was matched by increases in affordability, as the sampling of computers in the following table demonstrate.

Machine Release Year Cost at Release Adjusted for Inflation
ENIAC 1945 $400,000$5,288,143
UNIVAC 1951 $159,000$1,576,527
PDP-1 1963 $120,000$1,010,968
Apollo Guidance Computer 1966 $200,000$1,599,388
Commodore PET 1977 $795$5,282
Apple II (4K RAM model) 1977 $1,298$8,624
IBM PC 1981 $1,565$4,438
Commodore 64 1982 $595$1,589
16" MacBook Pro (base model) 2020 $2,399$2,399

Not surprisingly, governments, corporations, schools, and even individuals purchased computers in larger and larger quantities, and the demand for software to run on these platforms and meet these customers’ needs likewise grew. Coupled with this rising demand for programs was a demand for skilled software developers, as reflected in the following table of graduation rates in programming-centric degrees:

Unfortunately, this graduation rate often lagged far behind the demand for skilled graduates, and was marked by several periods of intense growth (the period from 1965 to 1985, 1995-2003, and the current surge beginning around 2010). During these surges, it was not uncommon to see students hired directly into the industry after only a course or two of learning programming (coding boot camps are a modern equivalent of this trend).

Try to imagine yourself taking a professional programming job after your first programming course - what quality of software do you think you would be writing?

For that matter, how do you write programs now? Do you read the entire assignment before you start writing your program (if you’re like most of my students, I know you don’t). Do you draw out diagrams of your software’s architecture before you start coding? Do you write down exactly what you want the program to do before you start coding? Or do you just dive in and start writing code?

This latter approach is often called cowboy coding, after the old spaghetti westerns where the protagonist does not play by the rules. Cowboy coding is marked by a lack of discipline and process. Effectively it it the antithesis of software engineering.

1. Edsger Dijkstra, “The Humble Programmer”, Communications of the ACM, October 1972↩︎

# Evolution of Programming

The poor programming practices of cowboy coding and the growing numbers of unskilled programmers did not go unremarked. In fact, many of the programming language features you are familiar with were developed explictly to counter these trends - i.e. to ‘idiot-proof’ programming.

Consider all the control-flow constructs you know: the for loop, the while loop, the if/else statement, the switch statement, the ternary operator, etc. None of these existed in early programming languages. Instead, the role they each played was provided by a single multipurpose command, GOTO. A GOTO would jump program execution to a labeled point in the program, much like a choose your own adventure book would ask you to turn to a page. And much like an unskilled author could create a nightmare of such a book, an unskilled programmer could make an absolute mess.

Structured programming is the programming paradigm that introduced these control-flow structures, initally in ALGOL in the late 1950’s, and have been a staple of programming languages since. In fact, structured programming has become so ingrained in modern programming langauges that I wouldn’t be surprised if you had never heard the term. But structured programming didn’t just introduce control-flow constructs, it also gave us procedures and code blocks, the basis of functions. That’s right, the humble concept of a function did not exist in early programming languages!

Other paradigms - Object-Orientation, Functional Programming, and Logic Programming were also born primarily as a way to make programs easier to understand, write, and verify.

The tools used for programming also evolved side-by-side with the languages. Punched Cards were the primary means of creating programs until the mid-1970’s, and many legacy systems continued to use this technology into the 1980s. Punched cards were punched using a specialized keyboard similar to a typewriter known as a keypunch that, insead of leaving inked charcacters on paper, punched holes in cards. There was no undo button - mistakes had to be repunched.

With the advent of the computer terminal in the late 1960’s

Similarly, the debugging tools available to programmers have evolved over time. Only after the migration from punch-card systems to CRT monitors and keyboards did command-line debuggers appear - simple programs that could dump the contents of memory to the monitor as the program being debugged was running. Symbolic debuggers (those that hold onto symbol names parsed during the compilation process and attach the corresponding in-memory values) and the ability to insert breakpoints (locations in code where execution would be paused) did not appear until much later, as this 1984 PC Magazine ad attests:

The modern Integrated Development Environment (IDE), programs like Visual Studio, XCode, Eclipse, Atom, VS Code, and the various JetBrains products, which combine program editing and debugging, simply didn’t exist for much of programming history. The first IDE was TurboPascal introduced by Borland Ltd. in 1983. Visual Studio did not appear until 1991.

# Software Project Management

Beyond the increasing demand for programs, the large-scale recruitment of unprepared programmers, and the lack of good development tools, another factor marked many failed projects, mismanagement.

Software was a new kind of product, and nobody had a really strong grasp of what would be invovled in developing it. The Steve Jobs quote this chapter opened with, “When we started off we didn’t know how to spell software” is telling. Similarly, Dick Battin, one of the engineers behind the Apollo Guidance system admitted “… we had no idea how we were going to do this job, other than to try [to] model it after the Mars probe.” 1

If the programmers and software engineers who were creating the software didn’t have a clear picture of what would be involved in creating software products, the business professionals who were tasked with managing them had even less. Barry Boehm’s 1981 text Software Engineering Economics sought to provide guidance to these project leaders, applying the principles of scientific management to software development and providing detailed models for mathematically estimating project costs, time, and personnel.2 The resulitng Constructive Cost Model (COCOMO) was a first of its kind, and was widely adopted by the business community.

An example of one of the equations from this text is:

$$MM = C (KDSI) ^ k$$

Where:

• $MM$ is the time spent on the project, measured in man months (152 working hours)
• $C$ is a constant
• $KDSI$ is the number of source code lines in the delivered product
• $k$ is another constant

A common falicy arising from the practice of using man months as a metric is the idea that adding more people to a project will get it done sooner. This is the basis for Brooks Law: adding more people to a late software project will make it later. This should be obvious to you as a programmer; bringing new programmers on board to help with an existing project means they must learn the details of the system being built, and the only people who can teach them those details are those that are currently building it. Increasing team size also increases meeting time and bureaucracy involved.

Brooks Law was formulated by Fredrick Brooks in his book “The Mythical Man-Month”.3 Brooks was one of the managers for IBM’s OS/360 project, and this book encompasses many of the mistakes he made manging the project and the lessons he learned from them. These are mistakes he sees other managers continuting to make. He once quipped:4

Some people have called the book the "bible of software engineering." I would agree with that in one respect: that is, everybody quotes from it, some people read it, and few people go by it."

Many of the management techniques applied to software development in the early days are based on clear misconceptions of what the eneavor of software development really is. It is both an exacting engineering challenge and a creative activity. Efforts to ‘improve productivity’ often have the inverse effect - as Brooks would attest, making a team larger increases the amount of communication required. Similarly, studies have shown that ‘crunch time’, the practice of asking programmers to work late hours and weekends, actually leads to negative productivity, as tired programmers make errors that require more time to fix than was saved.

Similarly, the metrics used by software managers can be flawed. Lines of code may make sense as a metric when you’re writing COBOL or FORTRAN code, but the use of modern programming languages and libraries greatly reduces the length of programs. For example, in Node you can write a fully functioning static web server with just one library and four lines of code:

const express = require('express');
const app = new express();
app.use(express.static('public'));
app.listen(80);


And, if you don’t care too much about readability, you could reduce this to one line! Conversely, if you are being evaulated by the number of lines written, you can certainly make such a program far, far longer. This leads to bloat, and also makes your code more difficult to read and maintain. Either way is a losing proposition - it is far better to write programs in a comfortable-to-read manner, as this makes them easier to debug and maintain.

Unfortunately, many of the mistakes Brooks identified continue to crop up in modern software development projects, making poor project management another major contributor to the software crisis.

1. Universe Today, “The story of the Apollo Guidance Computer, Part 2” ↩︎

2. Barry Boehm, Software Engineering Economics, Prentice Hall, 1981. ↩︎

3. David Brooks, The Mythical Man Month, Addison-Wesley, 1975. ↩︎

4. Daniel Roth, “Quoted Often, Followed Rarely”, CNN Money, Dec. 12, 2015. ↩︎

# The Software Crisis

Now that we know some of the causes, what exactly was the software crisis? It is a period of time marked by bungled software projects, whose common problems included:

• Projects that ran over-budget
• Projects that ran over-time
• Software that made inefficient use of calculations and memory
• Software was of low quality
• Software that failed to meet the requirements it was developed to meet
• Projects that became unmanageable and code difficult to maintain
• Software that never finished development

Let’s review some representative examples.

### The IBM OS/360 Project (1963-1965)

This ambitious project was undertaken by IBM to create a single operating system that would run on all mainframes manufactured by IBM. While operating systems that can run on different models of computers are commonplace today, at one time this was a very novel idea. IBM was offering half a dozen mainframe products at the time, and each had is own, incompatible, operating systems. On April 7th, 1964 IBM announced a new lineup of products - 6 models of computers, with 44 peripherals, and all were to be compatible with each other! The new OS/360 would make this feat possible.

But the software development staff struggled to accomplish the central goal of OS/360 - the ability to run more than one program at a time, and other issues began to crop up. IBM responded by hiring 1,000 more developers to assist the project, spending more in a single year than had been planned for the entire product development process! The operating system was eventually shipped, but a month late and far over budget.1

### The Therac-25 (1985-1987)

Perhaps the most chilling software failure in the history of Computer Science is the Therac-25, a machine to deliver radiation therapy to cancer patients. The software used was repurposed from the earlier Therac-6 and Therac-20 model, which had hardware interlocks to prevent certain kinds of failure conditions. The Therac-25 removed these in favor of software-based safeties. A race condition in the controller software, along with poor user interface design and assorted other issues could lead to incorrectly delivered doses of radiation - as much as 100 times the intended dose. Between 1985 and 1987 at least six patients were exposed to dangerous doses of radiation and developed symptoms of radiation sickness; three of these patients died 2.

### The German Toll Collect system (2003)

Germany contracted with the Toll Collect, a syndicate involving large corporations including DaimlerChrysler, Deutsche Telekob, and Cofiroute, to establish an automated toll-collection system that would use GPS receivers mounted in trucks to collect Autobahn usage data and automatically bill truckers’ accounts for the usage. The project was slated to open in August 2003, but was eventually cancelled by the German government when the project failed to be ready by February 2004, after Toll Collect admitted the system would not likely be ready until 2006. Over 156 million euro of revenue was lost due to uncollected tolls before the contract was canceled. 5

### The Healthcare.gov Launch (2003)

The Healthcare.gov marketplace was a cornerstone of the Affordable Care Act - a website where Americans without access to employer-based health insurance could enroll in a competitively-priced insurance plan. At launch the site was plagued with technical issues, and only an estimated 1% of its users were able to complete an enrollment, and many of these applications were failed for missing information.

### Reliability

Reliability refers to the frequency of error conditions. It may not be a big deal for your text editor to occasionally crash. But for the control code in a pacemaker or the autopilot in a commercial jetliner, error conditions can be life-threatening.

### Maintainability

Maintainability refers to the ease with which bugs are fixed and new features are added to a program. There is little software developed today that will not see new releases for the purpose of minor updates and bug fixes, let alone new major versions.

### Extensibility

Extensibility also refers to the ease with which new features are added to a program, but the mechanisms by which this is done are different. With maintainability the features are added as part of the core software. With extensibility, these are typically done externally to the core code, through plugins or by accessing an API (application programming interface). This allows the system to be expanded, sometimes by third parties, without needing to replace the existing software installation.

### Security

Security refers to how well-protected the program’s function and data are from malicious agents (both human and software-based). Programs that handle sensitive information typically need higher levels of security. The prevalence of Internet connectivity in modern life means that programs are no longer running in an isolated environment - even simple desktop applications need to pay attention to security risks!

# Features

Features are another way of describing software, and often get confused with requirements. A feature is a way of describing the software, and tends to be quite high-level. In this sense they are much like a business requirement, but without the focus on the business side of the need.

Usually, a feature is tied to multiple requirements, i.e. a feature might be:

The business requirements derived from this might be:

• The gift basket will be accessible by the user’s family and friends, and they will be able to purchase items in the basket for the user from it
• A user purchasing gifts in this fashion should be able to bundle multiple purchases for different individuals in a single transaction
• Individual gifts in the transaction should have the option of different delivery dates
• When items are purchased, they are no longer displayed in the gift basket

And the functional requirements would drill into each of those requirements, describing details the designers would need to know to design the software:

• Users can view their gift basket by clicking a similar icon in the right side of the menu
• This icon should also have a number in a pill next to it, indicating the number of items in the basket. This should update dynamically as items are added and removed from the basket.
• While viewing the gift basket, the user can remove items by clicking a button next to the item
• In the interests of privacy, the user’s personal information should not be displayed to the searching user
• The friend or family can initiate a gift purchase by clicking a ‘Send this gift’ button next to items in the gift basket.
• This adds the item to the user’s own shopping card, with a visual indicator that it is a gift being sent to the recipient
• The user should be able to specify the date the gift should arrive, within one year of purchase date.
• And so on…

You can see in this example how a simple feature expands in detail as you move from business requirements into functional requirements. You also probably also note that in carrying out this process, you will likely need to return to your customers for clarification of their business processes and specific needs.

Similarly, this process suggests non-functional requirements. To take purchases, for example, we must process credit cards, which implies we’ll need to integrate with a credit card processing service. Additionally, if gifts are able to be sent up to a year after purchase, we’ll need warehousing facilities for storing purchased gifts, and additional software to trigger the shipping process at the appropriate time.

# Discovering Requirements

A final challenge in discovering requirements is that your customers may not do a great job of telling them to you. We sometimes describe requirements as falling into one of three categories:

• Conscious
• Unconscious
• Undreamed

The conscious requirements are those your customer is aware of; correspondingly, they’re the easiest to gather because the customer shares them.

In contrast, unconscious requirements are those that are so deeply ingrained in the way the customer thinks and works that it doesn’t even occur to them that someone not involved in their work would not see it. A common example is units of measurement - a nurse or doctor thinks in terms of cc’s (cubic centimeters) as the default unit of volume whereas most of us might use tablespoons, cups, or fluid ounces.

This is why it is important for requirements gatherers to spend significant time with customers, ideally following them through their daily work processes - to see with ‘outside eyes’ the process they engage in. This is very similar to observation methods used in the field of anthropology - a few elective courses in that field will make you a far better requirements gatherer.

Finally, undreamed requirements are those that the user hasn’t even imagined. Most often, this category consists of things we could do because we are writing software and the technologies we can integrate into it, of which the typical user is unaware.

For example, one of the more common software development tasks is to take a process that used paper forms and translate it into software. Must customers will describe their needs as a one-to-one translation of the paper process into a digital one. But there usually are lots of opportunities for making the process more efficient by linking data in ways that isn’t possible for a paper process… sharing these opportunities is a great way to ensure you are making software that improves the lives of your customers!

# Requirement Gathering Techniques

There are many techniques used to gather requirements, which vary in their formality and approach.

## Formal Stakeholder Methods

Most requirement gathering begins with working with the stakeholders of the software project - those individuals who will be using or impacted by the software. It is important to remember to include all stakeholders - there is a common mistake made where the requirements gathers focus on the requirements identified by a select group of stakeholders, and ignore the others.

In working with these stakeholders, it is common to employ formal methods adopted from the social sciences. Formal methods are systematic in their application and when applied well can provide a clear picture of complex interactions and ideas. These methods include:

• Interviews include a ‘protocol’, a list of questions the interviewer should ask the interviewee. A good interview is conversational, and the interviewer should pursue additional threads that come up in the conversation to identify additional unconscious or undreamed requirements.
• Focus Groups are similar to interviews, but involve a group of stakeholders. These allow you to reach more stakeholders in a shorter period, but can fall prey to consensus thinking (where a handful of stakeholders steer the discussion and therefore requirements found in a certain direction).
• Observations involve observing stakeholders in their usual workflow routine. These are more time-intensive, but can result in a much better understanding of the customer’s needs - especially unconscious and undreamed requirements.
• Document Analysis is systematically reviewing documents related to the process. For example, in converting a paper process to a digital one, you should examine all the forms involved in the paper process.
• Surveys are a good way to get a lot of stakeholder response with a minimum of time. However, determining what to ask in the survey can greatly influence its value. Usually you’ll work from data supplied from other methods, and use surveys to validate what you’ve found or help assign priorities.

## Research and Design Approaches

Not all projects involve building a solution to a known problem - sometimes the point is to create something unique and (hopefully) desirable. For this kind of project, approaches borrowed from research and design may be more appropriate. These approaches can also be used to address unknown aspects of a more traditional problem-solving software project. These can include:

• Brainstorming is an activity where the developers throw out as many ideas as they can come up with. During the first stage, no idea is too outlandish. Then in the second step, these ideas are evaluated, winnowed, and combined into a cohesive direction. Brainstorming can help encourage creative and out-of-the-box thinking.
• Prototyping involves rapidly building a part of a system to determine if a particular approach is possible and worth pursuing. When used this way, a prototype is a proof-of-concept, and will not be integrated into the final project. This frees the programmer to use quick-and-dirty approaches (i.e. cowboy coding) to building the prototype.
• Reverse Engineering involves taking apart an existing product in order to create something similar. Consider Microsoft Excel and Google Sheets - they tend to use the same function names and syntax, and they function nearly identically as well, even though they have very different code bases. Not all reverse engineering involves competitor’s products either - another common reverse-engineering need in software is to reverse-engineer a legacy system in order to replace it.

# Conflicting Viewpoints

Along with the risk of failing to address the needs of a group of stakeholders, another common challenge in requirements gathering is to understand that different parties in the development process have different ways of looking at the project and the requirements, which can cause issues down the road.

Consider the Tree Swing cartoon, a classic humorous graphical metaphor for communication challenges arising from the different backgrounds of participants in a project:

As a software developer, you need to both learn to recognize the viewpoints of your stakeholders and respond to them appropriately and professionally. These skills are best developed through practice, so be sure to try to see the project from your stakeholder’s perspective!

# Summary

Requirements gathering sets the stage for the rest of the waterfall process, and is critical for understanding the needs an scope of the program you will be developing. This process begins with obtaining business requirements from the customer, and should include input from all stakeholders. This information is gathered through formal information-gathering processes borrowed from the social sciences.

These business requirements should be broken down into functional requirements fine-grained enough to give the developers a clear picture of what the software will need to accomplish. Moreover, they need to be comprehensive enough to not leave developers with unanswered questions. For novel functional requirements prototyping and brainstorming can be useful in sussing out possible implementation approaches and their feasibility.

The outcome of this process is a comprehensive document detailing the requirements of the software. It will commonly include sketches of proposed user interfaces and a discussion of how the software will integrate with other systems. It is also common to identify priorities of the various requirements.

# The Design Phase

Let’s come up with a plan!

# Introduction

The second step in any kind of software development project should be to develop a plan of how the software should be built - ideally before any code is written. This is what design is all about. This is also the antithesis to cowboy coding which is likely how you learned to program. Working on a software system without a clear plan lies at the heart of many software project failures.

This section will examine in detail how such plans are developed and documented.

### Key Terms

Some key terms in this chapter are:

• Design Document
• UML

# Design Document

The outcome of the design phase is a design document. It provides a design, or specification, for a software system. You can think of it like an architect’s blueprints provide the details for construction tradesmen to build a building - it provides rich enough direction that skilled laborers can follow in carrying out their portion of the work. In the waterfall model, the design document fulfills a similar role - it allows the work of building a software system to be broken down and assigned to different programmers focusing on a specific aspect of the system. If they follow the specification in the design, then the code created by each of these programmers works cohesively to create a viable program.

On the other hand, if the document lacks sufficient detail, or the programmers disregard aspects of the design and substitute their own ideas, the overall program will be compromised. Returning to the building metaphor, one of the classrooms in our department was originally built with the projection screen deploying over the exit door - a clear case of either 1) lack of detail in the plans, or 2) an installer not following them.

As you can imagine, a design document can grow quite large. To help combat this, Unified Modeling Language (UML) and other modeling approaches have been developed to convey design aspects visually, allowing the text of the document to focus on conveying key details. You’ve already worked with many UML diagrams and specifications in your education - most of your early programming assignments were essentially specifications. We’ll review those (and possibly introduce a few more) next.

# Class Diagrams

To put it succinctly, a UML Class Diagram represents the classes and the associations between the classes in an object-oriented program. Each class is represented by a separate box, and the associations between classes by arrows. The intent of the class diagram is to represent the complete structure (but not behavior) of an object-oriented program. This allows individual programmers to focus only a small part of the overall program - a class and the classes it has associations with. Combined with the other information contained in the design document, the programmer can implement their piece of the program and it should ‘just work’ when combined with the code written by other programmers.

### Visibility

In a UML class diagram, visibility (public/protected/private) is specified with symbols:

• $+$ indicates public
• $-$ indicates private
• $\#$ indicates protected

### Classes

The boxes representing a class are divided into three compartments. The first compartment displays the class identity, the second its attributes (fields), and the third its operations (methods).

Each element in a compartment appears in its own line, and uses the format described below.

#### Class Identity

The class identity is its name (again, capitalization matters). We can optionally preface it with a visibility symbol (if unmarked, we assume public). If the class is abstract, it should be italicized, and if it is static, it should be underlined.

#### Class Attributes

The attributes represent the state of the objects, i.e. its variables. These may use different names based on what programming language you are modeling (i.e. fields, properties, instance variables), but if it holds state, this is where it goes. These are represented by typed elements using the pattern:

$$[visibility] name : type [constraint]$$

The optional $[visibility]$ details the visibility of the element using the symbols described above.

The $name$ is the element’s name, and should be exact (i.e. capitalization matters). If the element is abstract, its name should be italicized. If it is static, the name should be underlined.

The $type$ is the element’s type (i.e. float/int/bool).

Finally, the $[constraint]$ any optional constraints, expressed in a pair of curly braces after the element.

For example:

$$+ weight: int \{weight: >= 0\}$$

Indicates a public field named weight of type int whose value should be zero or greater.

#### Class Operators

The operators represent the behavior of the object, i.e. its methods. These are specified using the format:

$$visibility name([parameter list]) : [return type]$$

The $visibility$ details the visibility of the operator (i.e. public/private/protected). Visibility is expressed using symbols described above.

The $name$ is the operator’s name, and should be exact (i.e. capitalization matters). If the operator is abstract, its name should be italicized. If it is static, the name should be underlined.

The $[parameter list]$ is a comma-delineated list of operators in the form:

$$name: type$$

Finally, the $[return type]$ is the element’s type (i.e. float/int/bool). If it can be omitted if the return type is void or undefined.

### Associations

The association (the relationship) between classes are specified by arrows between the class boxes. The format of the arrow, along with its direction, conveys details about the association.

Associations are classified as being has-a or is-a and weak or strong. The four combinations are therefore:

Association Type Representation
Realization weak is-a dashed arrow
Generalization strong is-a solid arrow
Aggregation weak has-a open diamond fletching
Composition strong has-a filled diamond fletching

The arrow is always in the direction of the relationship, i.e. from the class that has-a instance of the other class to that class, and from the class that is-a instance of another class to that class.

#### Realization (Weak is-a)

Realization makes an interface or abstract class “real” by implementing its methods. We call this weak because the interface or abstract class does not provide functionality to the implementing class.

#### Generalization (Strong is-a)

Generalization refers to extracting the parts that classes have in common and “generalizing” them into a base class. You probably know this relationship as inheritance. We call this a strong relationship because the base class provides functionality to the derived class.

#### Aggregation (Weak has-a)

Aggregation refers to one class holding references to another one - i.e. through a field of that type, or a collection of that type. It is a weak association because the object the aggregated object or objects can be swapped for other instances (or left null).

#### Composition (Strong has-a)

Composition also refers to one class holding references to another one. The difference is that with composition, those other object instances are typically created at the same time as the containing object, and are never swapped out for other instances. You can think of the whole group as a single object, even though it is multiple separate ones.

### Stereotypes

UML was intended to represent a generic object-oriented language. However, it was recognized that many languages have specific features not found in others. To allow UML to represent these, it also includes the idea of stereotypes - specifying language-specific features using a pair of angled brackets:

$$\langle\langle stereotype \rangle\rangle$$

For example, in C# properties are accessor methods (a get and/or set) which are treated as fields. We can represent this by applying a stereotype to a field, i.e.:

$$+Count:int \langle\langle get \rangle\rangle$$

Indicates the property Count has a get but no set method.

# Database Diagrams

Most production applications today utilize structured data that is commonly stored using a specialized application known as a database. For traditional relational databases, a number of modeling approaches have been developed, including UML database diagrams, Entity Relationship diagrams, and Crows-foot notation. The purposes behind these modeling approaches is similar to that of the UML Class Diagram - a database model allows its readers to 1) quickly set up the database structure and 2) understand how to access the needed information (i.e. how to author SQL queries to obtain the needed data).

This also means that the database design can be done by a separate team than the one building the program that will making use of the database. Thus, the structure of the database can be developed by experts in database design with an eye towards efficient modeling, storage and information retrieval, while the actual programmers using the database only need to be able to write queries. If the necessary queries are identified as stored procedures as part of the design document, then even less knowledge is needed on the part of the programmers - the stored procedures can be written by the database architects, and the programmers only need to know how to call them.

# UX Diagrams

A UX (for user experience, aka user interface) diagram visually presents what the user sees on the screen of a device running the program in a simplified form. These are also sometimes called wireframes (due to the diagram typically only showing text and outlines of controls) or bluelines (a term borrowed from architecture, where plans are drawn in blue pencil before begin printed in black and white). Typically, each screen of the user interface is drawn as a UX diagram, along with a description of the purpose of the controls on the page.

In addition to displaying individual screens in a UX, arrows can be added connecting screens to represent how the program’s state advances based on user interaction. The actions the user takes are typically used as a label for these arrows. Increasingly, UX modeling applications are employed to provide an interactive ‘click-through’ experience of the app, though most of these tools will also print a traditional diagram form.

UX diagrams provide several benefits. While most customers won’t understand other aspects of the design document, a UX diagram represents the part of the program they will be interacting with. Accordingly, this is the portion of the design they will be able to give the most feedback for - and that feedback may influence other aspects of the design. Second, to design a good UX, a developer must understand the customers’ needs and way of thinking about a problem – essentially, they must be familiar with the customers’ processes and discipline. With a good UX diagram, however, this understanding is not vital. As long as the UX designer understood the customers’ needs and captured it in the UX diagram, the user interface it specifies will make sense to the customer. The programmer need only implement it.

# Agile Models

Let’s Get Flexible

# CIS 642/643 Assignment Descriptions

What exactly are we doing?

# Introduction

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

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
* Address any concerns the customer has

Sprint Planning [customers and team]
* Discuss goals for the upcoming sprint
* 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:

2. Create a release tag for the sprint

#### Code Quality (20 points)

Does the code compile and run? Does it suffer from unhandled errors? Does it perform as described in the user documentation?

#### Coding Style (10 points)

Is there a consistent and understandable coding style employed throughout the code base? Are variable names consistent and descriptive of their roles? Is indentation used consistently to delineate nested code bodies?

#### In-Code Documentation (10 points)

Does the code include a detailed inline documentation description of each class, method, and function at their point of declaration? Is an auto-document style used for inline comments? Are non-obvious sections of code commented with a description of their purpose? Is the documentation legible, grammatically correct, and profanity free?

#### Licensing (5 points)

Does each file begin with a comment stating copyright and license information? Is the full text of the license included with the project code?

#### Developer Documentation (15 points)

Is the documentation sufficient to orient a new programmer to the codebase and describe where the important aspects of the code are located? Does the programmer documentation include diagrams of the code structures and how they interact (i.e. class diagrams, database diagrams, use-case diagrams) where appropriate? Does the documentation describe how to set up the development and deployment environments? Is the documentation legible, grammatically correct, and profanity free?

#### Test Suite (20 points)

Does the release include an appropriate test suite that performs unit and integration tests on the existing code base? Do all tests pass? If an automated test suite is not possible, does the release include 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.