CS 346 Application Development

Welcome to CS 346! In this course you will work on four-person project teams to design, develop and test a robust full-stack application.

Modern software is often too complex for a single person to design and build on their own. By working together, we can pool everyone’s talents to tackle much larger, more complex projects. Our goal is to use best-practices to design and build a commercial-quality, robust, full-featured application.

Course Description

From the course calendar:

CS 346 LAB,LEC,TST 0.50

Application Development

Introduction to full-stack application design and development. Students will work in project teams to design and build complete, working applications and services using standard tools. Topics include best-practices in design, development, testing, and deployment.

Prereq: CS 246; Computer Science students only

Sections

Classes are a mix of lectures, demos and team activities towards your final project. There are two sections, and each section meets Wed and Fri at the times listed below. You have to be registered in matching sections i.e. LEC/LAB 001 or LEC/LAB 002. Team members must all be registered in the same sections.

Sections Room Wed Class Fri Class
LEC 001/LAB 101 MC 2034 10:30a - 12:20p 10:30a - 12:20p
LEC 002/LAB 102 MC 2035 2:30p - 4:20p 2:30p - 4:20p

Motivation

There is an XKCD for every situation.

XKCD Code Quality XKCD Code Quality

Content from xkcd.com and licensed under the Creative Commons Attribution-Non Commercial 2.5 license.

Subsections of CS 346 F23

Chapter 1

Introduction

An outline of the basic course elements, including learning objectives, assessments, a weekly schedule of topics, and course policies.

Subsections of Introduction

Outline

Course Description

From the course calendar:

CS 346 LAB,LEC,TST 0.50

Application Development

Introduction to full-stack application design and development. Students will work in project teams to design and build complete, working applications and services using standard tools. Topics include best-practices in design, development, testing, and deployment.

Prereq: CS 246; Computer Science students only

Course Requirements

This course is restricted to Computer Science students. You must have completed CS 246 prior to taking this course, and you should be able to:

  • Design, code and debug small C++ programs using standard tools. e.g. GCC on Unix.
  • Write effective unit tests for these programs. e.g. informal I/O tests, unit tests.
  • Demonstrate programming proficiency in C++, which includes: understanding of fundamental OO concepts. e.g. abstraction, encapsulation; knowing how to use classes, objects, method overloading, and single inheritance; polymorphism; understanding how to use assertions, and how to manage exceptions.

Learning Objectives

On successful completion of the course, students will be able to:

  • Work effectively as a member of a software development team.
  • Use an interactive process to manage the design, development and testing of software projects.
  • Design and develop different styles of application software in Kotlin, using appropriate architectural and design patterns.
  • Design services that can provide remote capabilities to your application.
  • Apply debugging and profiling techniques to address design and performance issues.
  • Produce unit and integration tests as part of the development process.

Required Resources

There are no required textbooks for this course. This website is the primary source for reading material, recorded videos and other supporting materials. For those that want to pursue topics in greater detail, there are additional resources listed in each chapter.

You will need administrative access to a computer to work on the project. This system should be capable of running the toolchain described here. You will not be able to use lab machines for this course, since you do not have administrative rights on those machines.

Please check your system requirements early in the course, and ask the instructor if you have any concerns.

Title / Name Notes / Comments Required
Computer/laptop Windows, Linux or macOS with at least 8GB of RAM. Yes
Slides and lecture videos Will be made available on course website. Yes
Supporting slides/videos Will be made available on course website or via links to external resources. Yes

Course Staff

Faculty & Staff

  • Dr. Jeff Avery (j2avery@). Course Instructor, responsible for course design and instruction (profile).
  • Caroline Kierstead (ctkierst@). Instructional Support Coordinator (ISC), handles academic integrity and course accomodations.

Teaching Assistants (TA)

Contacting Us

We maintain Piazza forums where you can ask questions outside of class. We will try and keep up with questions asked during normal business hours (9 AM - 5 PM) but there is no guarantee of a prompt reply after-hours or on weekends.

You are also welcome to help one another out on the forums, of course! (Just avoid posting code).

Assessment

This course is designed around a single project that you will design and develop with your project team. Most course components are tied to the course project in some way. Team grade items are items where everyone on the team receives the same grade. Personal grade items are individual grades.

Info

The course schedule lists the deadlines for each of the following components.

  • Demos are in-person, at the times listed on the schedule.
  • All other components must be submitted by 11:59 PM on the date listed on the schedule.

The Learn course site has rubrics posted for each component, with details on how they will be assessed.

Item What it addresses Team Personal
Proposal Review planned features, identify concerns and design issues. 5%
Demos (4) Demo new features and get feedback. 4 x 5%
Final submission Submit completed project. 40%
Participation Kickoff & Demo participation; Project contributions. 15%
Quizzes Learn: 5 quizzes x 4% each. 20%
  • Proposal: You need to provide details of your project, including a clear definition of your users, a problem to be solved, and the features that you will implement to address this problem. See project activities.
  • Demos: During each sprint, you are expected to identify what requirements to address, assign and complete work, and have a product release ready to demo on the final day. You will be evaluated during the final demo. See project activities.
  • Project Submission: Your final project submission is the complete contents of your GitLab repository, including README, Wiki documents, Releases pages, and Source code. See project submission for details.
  • Participation: You are expected to meet regularly with your team, and participate in all aspects of the project. Your participation grade will be calculated at the end of the term, and will be based on project data (i.e. your relative contribution, out of 5 marks), and a score assigned by other team members (i.e. you will rate one another at the end of the project, out of 10).

Rating your team members

  • At the end of Sprint 4, every person should send Jeff an email with a rating score for each of their team members.
  • Rate their overall participation and effort in the course. “Did they contribute to the best of their ability?”
  • Rate (1-10): 1 (very poor) -> 3 (poor) -> 5 (average) -> 7 (good) -> 8/9 (great!) -> 10 (carried the project)
  • These should be anonymous!

Email format

  • Title: Team 123 Participation Grades
  • Body: Each person’s name and a single grade. You may write a comment if you wish but that is not required.
  • Quizzes: All quizzes are available in LEARN during the week listed on the schedule. They open by 10:00 AM on the Monday morning, and close at 11:59 PM on the Friday of each week. Late submissions will NOT be accepted. Once you start the quiz, you must complete and submit it within 30 minutes. Each quiz covers to the content up to the week prior to the quiz being open in Learn.

Course Policies

Team Participation

The expectation in this course is that you will form teams in the first couple of weeks, and work together towards meeting project deliverables. The following guidelines apply:

  • Students are responsible for matching up and forming teams. Teams must be formed by the end of the second week of the term (i.e. the add-course deadline). If you fail to find a team, you must inform the instructor by the end of the second week.
  • We do not guarantee you a team after the end of the second week. If you have not joined a team, and have not made some arrangement with the instructor, you may be required to withdraw from the course.
  • Course enrolment will be managed by the instructor to facilitate teams of four. If required, the instructor may authorize larger or smaller teams to accomodate everyone that is enrolled in the course.
  • If you fail to participate in project activities in the weeks leading up to the project proposal, you may be removed from the course. This is necessary so that teams can launch their projects successfully!

Absences

Students are expected to attend lectures and demos with their team. Failing to attend a demo will normally result in a grade of zero for that course component.

However, we recognize that circumstances may sometimes require you to miss a demo e.g. coop interviews, testing positive for COVID. If you need to miss a demo, the following guidelines apply:

  • You must contact the instructor and your teammates ahead of the due date. If missing a demo, you must coordinate with your team since they will be expected to proceed without you.
  • You must provide the instructor with a reason for missing the component (e.g. illness/COVID).
  • You are still expected to complete your work leading up to that deadline i.e. you are excused from presenting but not automatically excused for completing your work for the sprint!

The instructor will consider your request, and either (a) grant you an exemption from this component and redistribute the weight across other components, (b) grant you an extension, where you are expected to meet the requirement at a later date, or (c) not grant your request, in which case you have to either attend/contribute or accept a grade of zero. The decision to grant an exemption is at the discretion of the instructor.

Finally, you are allowed to miss at-most one demo per term without penalty, regardless of the reasons.

Self-Decaration

If you test positive for COVID or have COVID-symptoms, you are required to use the COVID self-declaration form. If you are ill but do not meet the COVID self-declaration guidelines, you should instead follow the guidelines and steps outlined in the Math Accommodations page.

In both cases, you must also follow the instructions listed above.

Short-Term Absence

You CANNOT use a short-term absence to delay a project demo (LAB components are exempt from STA requests). Contact the instructor if other assessments are affected.

Inclusiveness

It is our intent that students from all diverse backgrounds and perspectives are well-served by this course, and that student’s learning needs be addressed both in and out of class. We recognize the immense value of the diversity in identities, perspectives, and contributions that students bring, and the benefit it has on our educational environment. Your suggestions are encouraged and appreciated. Please let us know ways to improve the effectiveness of the course for you personally or for other students or student groups. In particular: 

  • We will gladly honour your request to address you by an alternate/preferred name or gender pronoun. Please advise us of this preference early in the term so we may make appropriate changes to our records. 
  • We will honour your religious holidays and celebrations. Please inform us of these at the start of the course. 
  • We will follow AccessAbility Services guidelines and protocols on how to best support students with different learning needs. 

Academic Integrity

In order to maintain a culture of academic integrity, members of the University of Waterloo community are expected to promote honesty, trust, fairness, respect and responsibility. Contact the Office of Academic Integrity for more information. You are expected to follow the policies outlined above for quiz and project submissions.

To ensure academic integrity, MOSS (Measure of Software Similarities) is used in this course as a means of comparing student projects. We will report suspicious activity, and penalties for plagiarism/cheating are severe. Please read the available information about academic integrity very carefully.

Ethical Behaviour

Students are expected to act professionally, and engage one another in a respectful manner at all times. This expectation extends to working together in project teams. Harassment or other forms of personal attack will not be tolerated. Course staff will not referee interpersonal disputes on a project team; incidents will be dealt with according to Policy 33.

Plagiarism

Students are expected to either work on their own (in the case of quizzes), or work within a project team (for the remaining deliverables in the course). All work submitted should either be their own or created by the team for use in their project. However, we realize that it is common practice to use third-party libraries and sources found online to solve programming problems. For this reason, the team is allowed to use third-party source or libraries for their project provided that (a) they document the source of this contribution in source code, typically as a comment, and in their README file, and (b) no single source constitutes more than 10% of their project. Failure to acknowledge a source will result in a significant penalty (10% or more) of your final project grade, depending on the severity of the infraction. Note that MOSS will be used to compare student assignments, and that this rule also applies to copying from other student projects.

OpenAI & LLM

Use of OpenAI systems (including ChatGPT, CoPilot and similar systems) falls under the umbrella of plagiarism: it’s a source that you must cite, and it’s contribution cannot exceed more than 10% of your code (per above policy).

Reuse of Projects

You cannot base your project in part or in whole on coursework that you have completed for a different course. Similarly, you cannot submit the same project to multiple courses for credit (i.e. CS 346 and CS 446 would require different projects to be submitted that do not share code or any componets).

Student Discipline

A student is expected to know what constitutes academic integrity to avoid committing an academic offence, and to take responsibility for his/her actions. A student who is unsure whether an action constitutes an offence, or who needs help in learning how to avoid offences (e.g., plagiarism, cheating) or about ‘rules’ for group work/collaboration should seek guidance from the course instructor, academic advisor, or the undergraduate Associate Dean. For information on categories of offences and types of penalties, students should refer to Policy 71, Student Discipline. For typical penalties check Guidelines for the Assessment of Penalties.

Intellectual Property

Students should be aware that this course contains the intellectual property of their instructor, TA, and/or the University of Waterloo. Intellectual property includes items such as:

  • Lecture content, spoken and written (and any audio/video recording thereof)
  • Lecture handouts, presentations, and other materials prepared for the course (e.g., PowerPoint slides)
  • Questions or solution sets from various types of assessments (e.g., assignments, quizzes, tests, final exams), and
  • Work protected by copyright (e.g., any work authored by the instructor or TA or used by the instructor or TA with permission of the copyright owner).

Course materials and the intellectual property contained therein, are used to enhance a student’s educational experience. However, sharing this intellectual property without the intellectual property owner’s permission is a violation of intellectual property rights. For this reason, it is necessary to ask the instructor, TA and/or the University of Waterloo for permission before uploading and sharing the intellectual property of others online (e.g., to an online repository). Permission from an instructor, TA or the University is also necessary before sharing the intellectual property of others from completed courses with students taking the same/similar courses in subsequent terms/years. In many cases, instructors might be happy to allow distribution of certain materials. However, doing so without expressed permission is considered a violation of intellectual property rights.

Continuity Plan

As part of the University’s Continuity of Education Plan, every course should be designed with a plan that considers alternate arrangements for cancellations of classes and/or exams.

Here is how we will handle cancellations in this course, if they occur.

  • In the case of minor disruptions (e.g. one lecture), the lecture content will be reorganized to fit the remaining time. This should not have any impact on demos or deliverables.

  • Cancellation of multiple classes may result in a reduction in the number of sprints and associated deliverables to fit the remaining time. If this happens, lecture content will also be pruned to fit available time. Assessment weights will be redistributed evenly over the remaining content if required to align with the material.

  • Cancellation of in-person (midterm or final) examinations has no effect on this course, since we do not have scheduled exams. Quizzes will continue to be written, but will be adjusted to the modified schedule as necessary.

Supports

Students with Disabilities

AccessAbility Services collaborates with all academic departments to arrange appropriate accommodations for students with temporary or permanent disabilities without compromising the academic integrity of the curriculum. If you require academic accommodations, please register with the AccessAbility Services at the beginning of each academic term. They will in-turn contact your instructors and arrange accomodations if necessary.

Mental Health Resources

If you or anyone you know experiences any academic stress, difficult life events, or feelings like anxiety or depression, we strongly encourage you to seek support.

On-Campus

Off-campus

  • Good2Talk (24/7): Free confidential help line for post-secondary students. Phone: 1-866-925-5454 (Ontario and Nova Scotia only)
  • Here 24/7: Mental Health and Crisis Service Team. Phone: 1-844-437-3247 (Waterloo Region only) 
  • OK2BME: set of support services for lesbian, gay, bisexual, transgender, or questioning teens. Phone: 519-884-0000 extension 213 (Waterloo Region only)
  • EMPOWER ME  1-833-628-5589 for Canada/USA. Other countries see: http://studentcare.ca/rte/en/IHaveAPlan_WUSA_EmpowerMe_EmpowerMe
  • EMPOWER ME in China:
    • China North  108007142831 
    • China South  108001402851 

Schedule

Class Schedule

This schedule lists the main activities for the term. Lecture topics are indicated on the schedule, and will be in-person. Demos always take place during Friday classes, on the dates listed below. Quizzes are not scheduled during class and must be completed on your own time.

Week/Agenda Topic Wed Class Fri Class (Submissions)
Week 01:
Sept 6-8
Introduction Introduction; Software process Planning; Requirements
Week 02:
Sept 13-15
Design Architecture; Software design Introduction to Kotlin
Week 03:
Sept 20-22
Implementation Functional Kotlin; Design patterns Build systems; Unit testing Proposal (5%), Q1 (4%)
Week 04:
Sept 27-29
Project Setup Development workflow; Team practices UI/Compose; Compose Multiplatform
Week 05:
Oct 4-6
Sprint 1 Jetpack Compose; Sprint 1 Kickoff - Q2 (4%)
Week 06:
Oct 11-13
Reading week Reading week
Week 07:
Fri Oct 18-20
- Demo (5%)
Week 08:
Oct 25-27
Sprint 2 Data & Databases; Sprint 2 Kickoff - Q3 (4%)
Week 09:
Nov 1-3
- Demo (5%)
Week 10:
Nov 8-10
Sprint 3 Web services; Service frameworks; Sprint 3 Kickoff - Q4 (4%)
Week 11:
Nov 15-17
- Demo (5%)
Week 12:
Nov 22-24
Sprint 4 Coroutines; Docker; Sprint 4 Kickoff Q5 (4%)
Week 13:
Nov 29-Dec 1
- Demo (5%)
Week 14:
Tues Dec 5
Final submission (40%)

Demo Schedule

This is the schedule that will be used for all of the Friday in-class demos (dates are listed on the course schedule above). On demo days, your team is only expected to be here for a 15-minute timeslot (i.e. for your team’s demo).

See Project Activities > Demo for details on how the demo will be run.

LAB 101: 10:30a - 12:20p (MC 2034)

TA / Time 10:30 10:45 11:00 11:15 11:30 11:45 12:00
Shahpar Team 101 Team 102 Team 103 Team 104 Team 105 Team 106 Team 107
Deborah Team 108 Team 109 Team 110 Team 111 Team 112 Team 113
Yiwen Team 114 Team 115 Team 116 Team 117 Team 118 Team 119

LAB 102: 2:30p - 4:20p (MC 2035)

TA / Time 2:30 2:45 3:00 3:15 3:30 3:45 4:00
Shahpar Team 201 Team 202 Team 203 Team 204 Team 205 Team 206
Gareema Team 212 Team 208 Team 209 Team 210 Team 211 Team 207 Team 213
Aniruddhan Team 214 Team 215 Team 216 Team 217 Team 218 Team 219 Team 220

Subsections of Schedule

Chapter 3

Course Project

Information related to the course project, including functional requirements, required technology stack, and the project activities that you will undertake as part of your project. Also contains a gallery - screenshots of some past projects for inspiration!

Subsections of Course Project

Requirements

What is a full-stack application?

A full-stack application is an app that has a front-end/client component that runs on a personal device (computer, phone), and one or more back-end components that run on a remote system (server) to provide additional capabilities.

There are multiple reasons to design a software system this way:

  • We might have data that needs to be shared across multiple devices, and backend services can manage access to that data.
  • We might need additional capabilities that a backend service provides.
full-stack
Image from Jake Northey, “Should We Use a Full Stack Development Team or Specialists?”

Many of the applications that you use are full-stack applications!

  • A web browser is a front-end client for a remote web server that contains shared data/pages.
  • A Twitter client pulls tweets from a number of online sources and presents them in a local client.
  • Microsoft Word is mostly a local application, but it integrates with OneDrive (Microsoft’s remote storage solution) for document storage.
  • Even a text editor like Visual Studio Code integrates with a number of remote services for automatic updates, maintaining extensions and so on.

You and your team will propose, design and build a full-stack application that runs locally but leverages one or more remote services (at least one of which you must design and write yourself).

What are your project requirements?

You can choose a project idea from the list below, or come up with your own idea. Regardless of which project you choose, you MUST meet some common requirements:

  1. You are required to use our technology stack, which are the technologies that we will discuss in lectures and support in-class. Deviation from this list requires explicit instructor permission (typically an email thread that you include in your project documentation).
  2. Your application needs to include at least one client and one service, that work together to provide functionality.
    • Your client can be an Android or a Desktop application (macOS, Windows or Linux). (Building a web client or iOS client requires instructor permission).
    • Your service should be a web service that processes client requests: typically this means storing, processing and returning data that is required by the client applcation. Optionally, you may find that your application needs multiple services (e.g. fetching data from an existing service, and storing data on a second service that you create).; this will vary based on the needs of your particular problem.
  3. Your client application must adhere to the conventions of that platform.
    • Desktop applications should support min/max/resizing; user functions should be clear and easy to find and use (through menus, toolbars, keyboard shortcuts); standard features like copy/paste, undo/redo should be implemented.
    • Mobile applications should use conventions for that platform: touch for selection, other gestures as appropriate; popup menus or hamburger buttons that expand to list functionality and so on.
  4. Your application must save and restore data between sessions. This typically means saving user preferences for the client on the local filesystem (e.g. window position and size), and shared data in database on your remote service (e.g. for a notes application, notes would reside in some database so that they were not lost if you rebooted the system).
  5. All other functional requirements are to be determined by you and your team. A significant portion of your final grade will be based on (a) how well you solve the problem for your user, and (b) how well your design “fits” the target platform. You are expected to propose (and design and implement) additional features to meet the needs of your users and the problem you are attempting to solve.
  6. You will be required to submit a proposal early in the course, describing your proposed features, and get feedback/approval for a custom specification before you can proceed with implementation.

Suggested projects

  • Users: Students that need to take course notes or wish to track their course information.
  • Purpose: Allow users to import and track information on courses that they’ve taken. e.g. ratings, lecture notes, grades on assignments, prof’s birthday. Store this information along with other related infomration such as PDF handouts, typed/written notes, pictures and so on.
  • Similar: Noteability, UWFlow
  • Functionality:
    • Local: Browse available courses, import and display course information from UW Open API. This could include course title, description, and when it’s offered. Save/edit text or rich-text notes.
    • Remote 1: Imports course information from UW Open API (read-only) to support these features.
    • Remote 2: Store notes and course comments in a custom service (read-write).
    • Remote 3: Integrate with UWFlow (read-write) – optional, long-term objective!
  • Users: Professionals that collaborate visually (students, designers, developers, architects).
  • Purpose: Provide a large canvas where people can sketch (e.g. virtual whiteboard), and changes are shared across multiple clients. Support freehand drawing, preformed shapes (that users can add, resize, move around the canvas), the ability to connect shapes and draw “box-diagrams”.
  • Similar: Miro
  • Functionality:
    • Local: Shape editor that allows you to drag/drop shapes, connect them, add text to a large canvas.
    • Remote: Stores drawings (“source-of-truth”) in a custom service and keeps multiple clients synchronized, so that multiple users can share a diagram in real-time.
  • Users: Anyone that wants to track recurring information.
  • Purpose: Have a single multi-purpose application to track day-to-day information (e.g. medication journal, work tasks, TODO lists).
  • Similar: Notion, DayOne, Obsidian
  • Functionality:
    • Local: Create, view, organize collections of notes; support rich formatting (rich-text, markdown or similar); integrate a calendar, ability to browse notes.
    • Remote: Store notes on a custom service, where they can be loaded across multiple devices. Multiple collected clients should remain synchronized as changes are made. This could (eventually) support synchronization across mobile and desktop applications.

Create your own project

Alteratively, you and your team are free to choose your own project topic. As a starting point you should:

  1. Review the project requirements above! You are required to meet these in all cases.
  2. Identify target users. Make sure that you are solving a a real problem for them. The interview process can help you define problems and areas to investigate.
  3. Identify the purpose of your application. e.g. devise a better way to store code snippets for a developer; build a e-book reader that stores books and user ratings; a system for UW students to plan courses using UW Open API data.
  4. Determine the basic requirements and features that would be required to address this problem. Look at competing products to get ideas. Brainstorm with your team and try to be original in solving the problem in a unique and better way!
  5. Identify local and remote functionality - make sure that you are dividing features across both a client and service.
Info

Here’s some APIs that might inspire you for a project idea.

  1. UWaterloo Open API: https://openapi.data.uwaterloo.ca/api-docs/index.html
  2. Notion API: https://developers.notion.com/
  3. Pokemon API: https://pokeapi.co/
  4. Marvel Developer Portal: https://developer.marvel.com/
  5. REST Countries: https://restcountries.com/
  6. NASA Open APIs: https://api.nasa.gov/
  7. Weather API: https://openweathermap.org/api
  8. Market Data API: https://polygon.io/
  9. News API: https://newsapi.org/
  10. YouTube API: https://developers.google.com/youtube/?ref=apilist.fun
  11. OMDb (Open Movie Database) API: https://www.omdbapi.com/
  12. DeckOfCards API: https://deckofcardsapi.com/
  13. Open Library API: https://openlibrary.org/developers/api

How these requirements contribute to your grade

Your grade will be based on your progress through the term.

  • Did you make progress at each step of your project? Did you and your team work effectively together?
  • How well you meet these requirements. Did you complete everything described above?
  • How well designed your application is. Did you ensure that you built a compelling, useful and usable application? Did you take short-cuts?
  • Did you go beyond the bare-minimum requirements? e.g. adding a second client, or expanding the requirements.
  • How complex is the problem that you were attempting to solve? Was this a challenge for you and your team?
  • Did you follow the prescribed process, including design, testing, and deployment?

GitLab Project

As part of your project activities, you will be creating project documents and other artifacts and storing these in a a GitLab project. This project should contain everything related to your project! This includes your project proposal, design documents, meeting minutes from your sprints, software releases that you produce and any other documentation that is required.

Info

Generally, we will not be grading your GitLab repository until the end-of-the-term (the exception is a product release page which you should be creating for each sprint demo!). Your final submission will include a number of documents all linked from your GitLab Project, plus source code, installers and so on.

1/ Project Setup

Your GitLab project must be setup as described in the Getting Started section, and should minimally include:

  • A project landing page (aka README, see below).
  • All related documentation and source code (see below).
  • Release pages for each sprint (see below).
  • Milestones corresponding to each sprint.
  • Issue lists for each sprint, including issues closed as part of that sprint.
  • Unassigned issues representing incomplete work.

2/ Documentation

2.1. README (Project Landing Page)

You should have a markdown file in the root of your source code repository named README.md. This will serve as a landing-page for your project (i.e. its the first thing that users will see when visiting your project page!). It should contain the following sections.

# SUPER-COOL-PROJECT-NAME

## Goal
A brief description of your project. What is it? What does it do?

## Team Members
List each person's name and email address.

## Screenshots/Videos
Optional, but often helpful to have a screenshot or demo-video for new users.

## Quick-Start Instructions
Instructions. Details on how to install and launch your application. 

## Project Documents
Include a link to your Wiki pages, see below.

## Software Releases
Include a link to your Wiki pages, see below.

2.2. Wiki

Your GitLab project has a built-in Wiki, where you can store more complex documents and project executables. It should contain the following documents:

  • Project proposal
  • Meeting minutes
  • Everything else mentioned in the final submission rubric

3/ Software Releases

Each sprint should produce an installable and runnable version of your project, which should contain the features that were completed during the sprint. The output from a sprint should be a release-quality build of your product, which you will store in this section of your project repository.

Your README.md file (from above) should include links to the components of each software release. Your software release should include:

  • Release notes: a markdown or text file, containing at least:

    • the release date (which should be the sprint demo date)
    • the version of this release (which you increment for each release)
    • a list of changes that were included.
  • Installers: this is a packaged version of your application that a user could use to install your software. You should support and test installation on at least 2 platforms (pick two from Linux, Windows, macOS - whatever you have available for testing).

    Acceptable forms of packaging include:

    • a zip or tar file that, when extracted, contains bin/ and lib/ directories, and a script that launches the application.
    • an exe, dmg or pkg file that, when executed, installs the application.

4/ Source Code Repository

Source code and other assets required to build your application should be stored in your project’s source code repository. The structure should look something like this by the end of the term.

.
├── .gitignore
├── .gitlab-ci.yml
├── LICENSE.txt
├── README.md
├── application
│   ├── build.gradle
│   └── src
│       ├── main
│       │   ├── java
│       │   └── kotlin
│       └── test
│           └── java
├── buildSrc
│   ├── build.gradle
│   └── src
│       └── main
│           └── groovy
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── releases
│   └── v0.1-release-notes.md
│   └── v0.1-installer.dmg
│   └── v0.1-installer.exe
│   └── v0.2-release-notes.md
│   └── v0.2-installer.dmg
│   └── v0.2-installer.exe
├── server
│   ├── build.gradle
│   ├── gradle.properties
│   └── src
│       ├── main
│       │   ├── java
│       │   ├── kotlin
│       │   └── resources
│       └── test
│           └── kotlin
├── settings.gradle
└── shared
    ├── build.gradle
    └── src
        └── main
            ├── java
            └── kotlin

Most of your repository contains the source code and related documents for your project. It is recommended that you follow the structure provided above, which will build properly in GitLab CI/CD.

Final Submission

There is also a final submission due at the end-of-term (see assessment).

Guidelines

  • Everything related to your project, and this final submission, must be included in your GitLab project. We will ignore content posted anywhere else.
  • We will read your documentation, install and run your application. We will also review your source code (from the main branch only) and all submission details.
  • Everyone on the team will receive the same grade for this component.

What to include

README.md

You should have a README file, as described in previous sections. This is your landing page for your project.

Main Sections

You should have documentation including these sections. Each section should be documented in your Wiki and linked from the README file. These can be separate pages, or a single page with sections - your choice on formatting and structure.

  • Project: Name of your project, list of team members, overview of the project goals.
  • Meeting Minutes: From your meetings during the term.
  • Requirements: A description of the problem that you are attempting to solve, and your target users. A brief description of the major features of your project (do not naively link to an issues list, but describe the features for your users).
  • Design: Class diagrams for your data models; architecture diagram. Discussion of any significant design decisions that were made (e.g. design patterns used, architectural style, how data flows). What technical decisions did you make that were beneficial? What technical decisions didn’t work out as well?
  • Discusssion: What best-practices were used. What worked well for your team? What would you do differently? If there were features that were not completed, discuss what happened and what you learned from it.

Installation Details

  • Instructions: links to your latest release, and installation instructions for both the client and service (if needed).
  • Software releases: link to each release page, including installers for both client and service.
    • You should have an installer for the client, and some way for us to run your service e.g. hosted in the cloud already, or runnable from a Docker image. Make sure to include instructions on how to install and execute everything!

Source Code

The complete source code to build your project should be committed.

  • All features committed to main branch, and your project builds properly from main.
  • Your issues list should align with your source code (i.e. closed issues are implemented, open issues were not merged to main).
  • You should include unit tests for major features and these should pass properly.

Gallery

Here’s a gallery of some projects that were created in past offerings of this course. Teams have a lot of leeway in choosing what to design and build, so each project is unique! Screenshots and videos are posted here with the author’s permission.

Editors

image-20230418111020096 image-20230418111020096
Inkwell, a rich-text note-taking application. Copyright (c) 2023 Benjamin Du, Yuying Li, Charles Shen, and Andy Yang.
Zircon Editor Zircon Editor
Zircon, a markdown editor with syntax highlighting. Copyright (c) 2023 Eddy Guo, Joshua Johnson, Mihran Mashhud, Tony Tascioglu, and Mrugank Upadhyay.
Notes Notes
Notes, an app for organizing short notes. Copyright (c) 2023 Hoang Dang, Inseo Kim, Guransh Khurana, Abhay Menon, Anshul Ruhil.

Real-Time Collaboration

Whiteboard Whiteboard
Whiteboard, a collaborative drawing space. Copyright (c) 2023 Terry Zheng, Jonathan Wang, Seth Hammell, and Alan Lee.
Whiteboard Whiteboard
Whiteboard, a collaborative space with real-time synchronization. Copyright (c) 2023. Anh Huy Nguyen Do, Chirag Jindal, Mayank Devesh Shrivastava, Pranav Sai Vadrevu. (video)
Whiteboard Whiteboard
Whiteboard, a collaborative drawing space. Copyright (c) 2023. Kevin Chen, Franklin Gao, Catherine Tao, Andrew Zhang. (video)
Chapter 4

Project Activities

The project activities that you will engage in through the term!

Subsections of Project Activities

Forming Teams

  • Goal: Form project teams.
  • Deadline: One week after the first lecture.
  • Assessment: None.

You are expected to form project teams in the first week of the course1.

  • Teams should consist of four people.
  • You all must be enrolled in the same sections of the course.
  • You must all attend in-person (i.e. this course cannot be taken “online”)

How do you find team members?

  • Join friends who are taking the course! If you are in different sections, ask the instructor, and they may be able to move you all into the same section.
  • Post in the course forums: we will have a forum thread where you can introduce yourself.
  • If you’re in-class, introduce yourself to people sitting near you.

Once you have a team formed, please email the instructor with details:

  • Section number.
  • Names and email addresses of your team members.
  • The URL to your GitLab project.
Tip

To be successsful, we suggest that you look for team members that share your goals, and your approach to the course.

  • Do you have the same work schedule? Are you available at the same times (e.g. mornings? evenings?)
  • Are you all willing to make the same time and effort commitment to the course? If your team wants to put in extra time to get an A+, then you need to make sure that everyone is on-board to do that.
  • Look for complementary skills! Not everyone needs to be a (fill-in-the-blank) programmer. There’s room for a lot of different skills to be applied to your project. Some teams have setup a team member as their designer, or project manager depending on what they need.

  1. We will attempt to enrol the correct number of students to facilitate teams of four people. If smaller or larger teams are required, you will to need to get permission and coordinate with the instructor. Failing to participate in the process may result in your being required to withdraw from the course. ↩︎

Project Proposal

  • Goal: Choose a project, and identify high-level project objectives.
  • Due: Typically the end of week 3. See the schedule.
  • Assessment: The guidelines below are meant to explain in detail what we want from the proposal. The rubric for grading it is listed in the Assessment section.

In the first few weeks, you and your team will choose a project, define requirements, and discuss design issues.

You should create a Wiki page in your GitLab project named Project Proposal, and link to it from the landing page of your project site (i.e. the top-level README file at the top of your project). This page should contain the following details, either on a single page, or multiple pages linked together.

(a) Project Plan

As discussed in the Planning slides, you should identify and detail:

  • Goals: What high-level project goals do you have?
  • Resources: How is your project staffed? Do you have any constraints on people’s time and availability?
  • Risks: What project risks can you identify? How will you mitigate these?
  • Milestones: Identify your sprints and deadlines (dates provided on the schedule), and a high-level plan of what to focus on for each sprint.

(b) Requirements

As discusssed in the Requirements slides, you should detail:

  • Problem: One or two-sentence summary of your project idea. What problem are you attempting to solve?
  • Users: The specific group of users that would be interested in your project
    • Interview at least 2 people in that group, and summarize their feedback in your requirements.
    • (Optional) Include a role-based or goal-based persona suitable for your project.
  • Functional Requirements: What features are you considering?
    • List your “top-ten” requirements: what features do you think are critical? This list doesn’t need to be comprehensive but should call out features that are core to your project.
    • Describe in a document but also link to your issues list in GitLab (i.e. Product Backlog of unassigned issues).

(c) Design

As discussed in the Architecture and Design slides, you should detail:

  • System Diagram: A box-and-lines diagram that shows the architecture of your application (aka architectural style).
  • Non-Functional Requirements: If applicable to your project, list any non-functional requirements (system qualities related to performance, or other factors). Most projects in this course will not have these, unless specifically identified by a user during interviews.
Tip

We will grade content in your GitLab project directly. Please ensure that:

  • you previously emailed the instructor your project URL when you formed your project team,
  • instructors and TAs have permission to access your project, and
  • everything is completed (documented in your project Wiki) by the deadline.

Sprints & Demos

  • Goal: Iterate in 2-week cycles.
  • Due: See the schedule.
  • Assessment: Participation grades for the demos. See the Assessment section.

Most of the term will be spent iterating on your project. Sprints start after the project proposal. You will be working in two-week iterations, called sprints. Over a two-week period, you will have a kickoff meeting, do some work, and finally demo that work to the TA.

Sprint Wed Fri
Week 1 Day 1: Kickoff Day 2: Daily standup
Week 2 Day 3: Daily standup Day 4: Demo
Info

You need to write down meeting minutes every time that you meet. These are very short. You can use either the meeting minutes or daily standup template if you wish. You can also use any other format that you wish as long as you store them in your GitLab project and include all of the information on the templates.

Day 1: Kickoff

The first day is the official kickoff, where your team collectively decides what you want to include in the sprint. Your primary task in this meeting is to choose items from the Product Backlog and assign them.

Here’s some suggestions to help you determine what to do during the sprint.

  • Address feedback from the previous sprint’s demo. You may have received feedback from the previous sprint. Treat suggestions from course staff as important - they represent your customers!
  • Address high-risk items early. This gives you time to pivot if needed, and also helps prevents you from investing too much time in a path that ultimately won’t work.
  • Look for blocking issues: items that are critical for other systems. Examples of this might be the class structure for business objects (e.g. data classes) that are used by other features.
  • Do NOT assign more work than you think you can do.

Outcomes from this meeting:

  • You should have issues logged and assigned to the team, representing the work for this sprint.
  • You should have meeting minutes documenting who was present, and any major decisions made by the team during the meeting.

Day 2/3: Standup

These are “working days” where your team gets together and does the actual work towards the sprint’s goals. You are expected to work in-class together; the instructor and TAs will be available to help you out.

You should have meeting minutes documenting who was present each time you meet, and any issues that you encounter.

Day 4: Demo

The last day of a sprint is demo to the course staff of what you’ve accomplished during the sprint. This is a checkpoint of sorts, where we can provide feedback and make suggestions.

Warning

Sprint attendance is required, and everyone on the team must attend the in-person demos. See course policies for more information.

Failing to attend a demo will result in a grade of zero for that component IN ADDITION to any penalty to your participation grade. Under exceptional circumstances where you MUST be absent e.g. coop interview, documented illness, you MUST discuss this with your team and the instructor ahead of time for any consideration.

This is what you should have completed before the demo:

  • You should have recorded meeting minutes for every team meeting prior to the demo.
  • The issues for the sprint should be updated
    • Completed issues should be closed in GitLab with details on what was done.
    • Code changes need to be committed and merged back to the main branch.
    • You should have unit tests that cover the features that you have completed.
  • You should also have readied a software release which details what you accomplished and has a link to an installer.

What does the demo look like?

  • Your demo will be informal and last about 10 minutes.
  • Using an INSTALLED version of the application, demo each completed feature, and answer any questions. (Your issues list in GitLab is a great way to drive this discussion).
  • The person who developed the feature should demo it.
  • All demos need to be run from the same machine.

Outcomes from this meeting:

  • The TA will assign a mark and your grade will be returned the week after the demo.
Chapter 5

Getting Started

Supporting tools and technologies that we use to track our project and support development practices. Programming language topics, frameworks and libraries are not included here, but will be discussed in lectures.

Subsections of Getting Started

Technologies

The following technologies are used in this course. See the setup toolchain for instructions on setting up these tools.

Required Technologies

Info

Most of these are required, but there is some ability to use different libraries if you wish. You need to obtain written instructor permission to deviate from this list.

Programming Languages & SDKs

  • Kotlin is the primary language used.
  • Java JDK is required for both desktop and Android.
  • Android SDK if you are developing an Android application.

Libraries

  • JUnit for unit testing.
  • Compose for building user interfaces.
  • Ktor for networking and building a web service.

Tools

Compatibility

It’s important to use matching versions of each of these libraries. The following version combinations are supported.

  • Java JDK is the JDK that you need to install in IntelliJ (typically both on your JAVA_PATH and in your project settings).
  • Compiling w. Gradle means that Gradle supports compiling with this version of the JDK.
  • Running Gradle means that Gradle can bootstrap itself with this version.
  • Kotlin Compiler, Compose and Ktor are the library versions specified in your project setup (e.g. `gradle.properties).
Java JDK download Compiling w. Gradle versions Running Gradle Kotlin Compiler Compose versions Ktor versions
17 (LTS) ⭐️ 7.3 7.3 1.9.10 1.5.1 2.3.5
18 7.5 7.5 1.9.10 1.5.1 2.3.5
19 7.6 7.6 1.9.10 1.5.1 2.3.5
20 8.1 8.3 1.9.10 1.5.1 2.3.5
Tip

Which one to use? JDK 17 is the best-supported version at this time (LTS stands for “Long-Term Support”, meaning that it will receive updates for the forseeable future). It’s suggested that you install that version, and specify Kotlin, Compose and Ktor versions in your build files as needed. Only install a newer version if you believe you need bleeding-edge language features (and are willing to address potential build/compatibility issues).

At this time, the project-template in the public GitLab repository is configured to use JDK 17 and works correctly with the most recent Kotlin Compiler, Ktor and Compose versions.

Setup Toolchain

We will be building Kotlin applications and services, and using the Java JDK as our deployment target. This means that you need to install the Java JDK and the Kotlin compiler on your development machine. It’s also highly recommended that you install the Intelli IDEA IDE for working with Kotlin, as it offers advanced language support and integrated well with our other tools and libraries1.

Check the technologies page for the recommended version numbers. Also, make sure that you and your team all install the same distribution and versions of these tools!

The following represents the minimum toolchain for the course.

Git

We use Git for version control, so you will need Git installed to perform operations on your source code.

Git is pre-installed on macOS and Linux; Windows users can install it from https://git-scm.org. Once it’s installed, you may need to update your path to include the Git installation directory. You can check your installation using the git version command.

❯ git version
git version 2.39.3 (Apple Git-145)

Java JDK

  • Download and install the JDK from Azul or OpenJDK (make sure to match your system architecture).
  • Add JAVA_HOME to your system’s environment variables, pointing to this installation.
  • Update your path to include the directory containing the Java executables.

For example, I am using JDK 18 (at the time I’m writing this). I have the following lines in my .zshrc:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
export PATH=$PATH:$JAVA_HOME/bin

You can check your installation using the java version command. Make sure the version matches what you expected to see.

$ java -version
openjdk version "17.0.8.1" 2023-08-24 LTS
OpenJDK Runtime Environment Zulu17.44+53-CA (build 17.0.8.1+1-LTS)
OpenJDK 64-Bit Server VM Zulu17.44+53-CA (build 17.0.8.1+1-LTS, mixed mode, sharing)

IntelliJ IDEA

IntelliJ IDEA is our recommended development environment. You can install it from https://www.jetbrains.com/idea/download/.

There is an Open Source Community version which will work for this course. There is also an Ultimate license, which includes better support for databases, web services and other frameworks that we’ll be using. This is normally a paid upgrade, but as a student you can get a free license2 to most of thier products, including this version of IntelliJ IDEA.

You can check the installed version by opening IntelliJ IDEA and looking at the IntelliJ IDEA - About dialog.

About Dialog

Kotlin

We will need a Kotlin compiler, and the Kotlin standard libraries. IntelliJ IDEA includes a Kotlin plugin, so if you have installed IntelliJ IDEA and you are working from the IDE, then you do not need to install Kotlin.

However, if you wish to compile from the command-line, or use a different editor, then you will need to install Kotlin manually. It can be installed from https://www.kotlinlang.org or from most package managers (e.g. brew install kotlin if you are a Mac user with Homebrew installed).

If you install the command-line version, you can check your installation using the kotlin -version command.

❯ kotlinc -version
info: kotlinc-jvm 1.9.10 (JRE 17.0.8.1+1-LTS)
Info

There are other libraries that are suggested on the technologies page e.g. Ktor, Exposed, JUnit. You do NOT need to manually install any of these! Early in the course we will discuss Gradle, our build system, which has the ability to import these libraries into our project automatically. It’s much easier than trying to manually manage all of the dependencies!

As long as you have installed Git, Java/JVM, Kotlin, and have an editor/IDE setup, you can start working on your project.


  1. Kotlin is supported in other editors, but make sure to install the appropriate language plugins for Kotlin, and Gradle. ↩︎

  2. https://www.jetbrains.com/community/education/#students ↩︎

Create a Project

You should create a single source tree, with subprojects for each major deliverables. e.g. an application project (for desktop), a server project (for your service) and models (for model classes that are shared between projects).

This ultimately needs to be setup in a project structure that looks like this:

cs346-project/
├── application/
├── gradle/
├── gradle.properties
├── gradlew
├── gradlew.bat
├── models/
├── readme.md
├── server/
└── settings.gradle.kts

application, server and shared all represent projects, with their own configuration files.

  • application is a Compose desktop project.
  • server is a Ktor project.
  • models are shared data model classes that each of the other projects use.

How to create the top-level project

Use the File-New Project wizard in IntelliJ to create a new Empty project. This will give you a top-level project with settings.gradle.kts, gradle/ directory and so on. Make sure to pick the correct version of JDK based on the Compatibility table.

Compose Desktop Compose Desktop

Move the application code into an application project:

  1. Create a directory named application.
  2. Move the build.gradle.kts and src folder into the application directory.
  3. Edit the top-level settings.gradle.kts and add the following line to the bottom of the file:
include("application")

This produces the following directory structure:

.
├── application
│   ├── build.gradle.kts
│   └── src
│       ├── main
│       └── test
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties
├── gradlew
├── gradlew.bat
└── settings.gradle.kts

Typing ./gradlew build at the top-level should build the project.

Next we’ll add the other missing projects: server and models.

Adding the remaining projects

The trick to adding more projects is:

  • Create the type of project using the IntelliJ IDEA Project Wizard for the type of project that you want.
  • Place it in a subdirectory from your main project. Each project directory should just contain the generated src directory, and the build.gradle.kts file. You don’t want anything else in the project subdirectory.
  • Finally update the settings.gradle.kts to add each project to the include statement.
include("application", "console", "shared")
Info

The project-template in the GitHub repo has a similar structure and can be used as a starting point.

Gradle Template

Here are sample configuration files for a multi-project Gradle build. It has the following structure:

project-template/
├── application/
├── build
├── console/
├── gradle/
├── gradle.properties
├── gradlew
├── gradlew.bat
├── models/
├── readme.md
└── settings.gradle.kts

application, console and shared all represent projects, with their own configuration files.

Tip

You can find the source code for this project in the GitLab Public Repository for this course, under sample-code/project-template.

Top-Level (Root)

The project root contains the settings.gradle.kts file, which defines the overall project structure.

pluginManagement {
    repositories {
        gradlePluginPortal()
        maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
    }

    plugins {
        kotlin("jvm").version(extra["kotlin_version"] as String)
        id("org.jetbrains.compose").version(extra["compose_version"] as String)
    }
}

rootProject.name = "notes-application"
include("application", "console", "shared")

It also contains gradle.properties, which includes project definitions and version numbers (which are referenced by the settings.gradle.kts.

org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
kotlin.code.style=official
kotlin_version=1.9.10
compose_version=1.5.1
ktor_version=2.3.5
logback_version=1.4.11

Gradle wrapper settings

There is a top-level gradle directory, containing the Gradle bootstrap files (the means by which Gradle downloads and installs itself when you run gradlew). These files are auto-generated by Gradle when you setup the project.

You might want to update the gradle-wrapper.properties to point to a recent version fo Gradle by changing the distributionURL line. In this example, we’re specifying Gradle 7.5.1.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Application project

The Application project contains a single src folder, containing the directory tree, and a single build.gradle.kts file which includes the configuration for this specific project. This is a Compose application, so we should expect to see application-style plugins and dependencies.

import org.jetbrains.compose.desktop.application.dsl.TargetFormat

plugins {
    kotlin("jvm")
    id("org.jetbrains.compose")
}

group = "net.codebot"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
    maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
    google()
}

dependencies {
    // Note, if you develop a library, you should use compose.desktop.common.
    // compose.desktop.currentOs should be used in launcher-sourceSet
    // (in a separate module for demo project and in testMain).
    // With compose.desktop.common you will also lose @Preview functionality
    implementation(compose.desktop.currentOs)
    implementation(project(":models"))
}

compose.desktop {
    application {
        mainClass = "net.codebot.desktop.MainKt"

        nativeDistributions {
            includeAllModules = true
            targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
            packageName = "client"
            packageVersion = "1.0.0"
        }
    }
}

Console project

The Console project has a similar structure to the Application project, with a single src folder and a build.gradle.kts file for this project. This is a console application so it doesn’t need Compose support.

plugins {
    kotlin("jvm")
    application
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    implementation(project(":models"))
    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

kotlin {
    jvmToolchain(8)
}

application {
    mainClass.set("net.codebot.console.MainKt")
}

Models project

Finally, the Models project provides services to both the Application and Console projects. It’s basically a library - not something that we execute directly, but code that we need to pull into the other projects. We keep it in a shared project to avoid code duplication.

Here’s the relevant build.gradle.kts.

plugins {
    kotlin("jvm")
    kotlin("plugin.serialization") version "1.9.10"
}

group = "org.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.5.1")
    testImplementation(kotlin("test"))
}

tasks.test {
    useJUnitPlatform()
}

kotlin {
    jvmToolchain(8)
}

Reference

IntelliJ IDEA

IntelliJ IDEA Home

Git & GitLab

Git Home

Gradle

Gradle Home

Kotlin

Kotlin Language

Compose User-Interfaces

Ktor Networking

FAQ

Logistics

How does this course work?

You team up with other students, pick a project and execute on it! This means choosing requirements, designing a solution, and building a complete application, with unit tests, release notes, and an installer.

You are expected to iterate on a solution over the course of the term, and meet with a TA every 2 weeks to discuss your progress. Your grade is based on your team’s ability to deliver something that effectively meets your user’s needs.

There are also lectures to introduce technical content and teach you best practices for working as a team. See the schedule for details.

What’s to prevent me from joining a team and then ghosting them?

This course is a great opportunity to gain significant development experience as part of a team! You won’t benefit from the course by just coasting through it.

Concretely, you are marked based on attendance and participation. Your grades will suffer dramatically if you don’t participate. In extreme circumstances, the instructor can and will remove you from the course in the first few weeks if you don’t participate.

How do we “hand in our work”?

You don’t need to explicitly submit anything. All your work will be stored in a GitLab instance which the course staff can access directly for grading. Make sure your work is complete and documented by the appropriate deadline.

How can I track my grades?

Your grades are tracked in Learn. Grades from Friday demos are typically available by the following Tuesday.

How can I learn all of this material?

It’s completely manageable. Keep in mind that in this course, you don’t have quizzes, midterms or other assignments: it’s just you, your team and your project. The course is designed so that the time you might spend on those things in another course will be spent here reading, tinkering, and working together on your project. The lectures are focused, fairly technical and designed to teach you what you specifically need to know at that time, so make sure to attend. There’s also reference material that might be useful.

Technology Stack

Why are we using this technology stack?

We have specific requirements for our technology stack:

  1. All our development tools need to be supported on Windows, macOS or Linux. This is a hard requirement because we cannot realistically force you to purchase specific hardware for this course, and students often have a mix of different systems. This is more of a challenge than you might expect since many tools are locked to one specific platform, e.g., you cannot write Swift applications unless you own Apple hardware; C# is only useful for building Windows applications and not Linux applications.
  2. We need to support building modern graphical user interfaces. There are only a handful of GUI toolkits that we can support given (1). e.g., SwiftUI is a non-starter.
  3. We want you to have the ability to build your choice of desktop or mobile native applications. We prefer native applications over web applications.

Can I use my preferred technology stack instead?

No.

… but I learned React on my last work term.

Sorry, but we cannot support different tech stacks.

It takes a lot of effort to build and support a course like this, and the course materials rely heavily on our technology decisions, i.e., lectures are based on our tech stack; the TAs know how to support you with it, and it’s what will be discussed on forums. It also happens to be a great tech stack with a lot of real-world applications, so think of this as an opportunity to expand your skills!

Can’t I use Vi/Neovim/Emacs/Sublime for development?

You’ll find that IntelliJ IDEA (or Fleet) offers advanced features not available in those other editors, which is why we recommend an IDE. But hey, you do you.

Project Help

Set up my computer?

Our list of recommended development tools is listed under the Getting Started > Technologies page.

Set up my project in my IDE?

For a single-target project (e.g., an Android or desktop application) you can use the New Project Wizard in IntelliJ IDEA, or create the project using gradle init. For more complex projects, see Getting Started > Creating a Project.

Create an installer for my program?

For a Compose desktop application, there is a set of Gradle packaging tasks: Gradle > application > Tasks > compose desktop > package*. You probably want to packageDistributionForCurrentOS which will build a regular installer for the OS that you’re currently using.

For Android, it’s acceptable to build an APK file (Build > Generate APK) instead of a full installer. This file can be drag-dropped onto a running AVD to run the program.

Finally, there are third-party installation tools if you want something more sophisticated. e.g. Conveyor.

Fix an installer that won’t run?!

Here are some common errors to watch out for (all related to the build.gradle.kts configuration file):

  1. You need to specify that you want to include all modules in the installer.
nativeDistributions {
 includeAllModules = true
 targetFormats(TargetFormat.Dmg, TargetFormat.Msi, TargetFormat.Deb)
 packageName = "cs346-project"
 packageVersion = "1.0.0"

}

  1. The version property defaults to “1.0-SNAPSHOT”. You MUST change this to the format 1.0.0 - see Semantic Versioning for details. You should probably be incrementing this with each software release/demo.
group = "com.example"
version = "1.0.0"
  1. JDK 20 and later aren’t fully supported by all libraries yet, so you should really use an older version (see Getting Started > Technologies). Make sure to set in the project settings (File > Project Structure > Project) and the Gradle project settings (IntelliJ > Settings > Build > Gradle)

If your installer fails when you execute it, try checking some of the other related tasks in the Gradle Menu in IntelliJ. e.g. compose desktop > runDistributable. The Gradle tasks in this section represent the subtasks that the installer builds and if you run them in the IDE, you will get more detailed feedback than you would from running the installer manually.

Find a user’s home directory

If your application writes data (to a file-based database, or even just a file) you need to make sure that the file location is writable. An easy way to accomplish this is to write to the user’s home directory, which is always writable for a given user. You can find their home directory in Kotlin by querying the environment:

val homedir = System.getProperty("user.home")