Programming Projects

Quick Reference

Grading

The grading system of complex projects differs greatly from that used in entry-level courses and in coding questions in exams:

  • Your code must compile and run!

  • The grader grades your code by running rather than by reading them!

  • A program compiles and runs through GNU make using commands like make, ./main, make test-all, make test-run, etc.

  • You should not expect any partial credits for code that cannot be tested by running your program. The grader do not have the responsibility to read, debug and understand your unfinished source code.

Project Workflow

This workflow is beginner oriented. Students may develop their own workflow as they gain experience in programming. However, there is still something even the experienced students can learn from here.

Design/Modelling Stage

In this workflow I assume that you start from a problem description to finish an application to solve a problem. In the real-world projects, many steps are already finished and you will be asked to start from implementation specification such as UML class diagrams, detailed descriptions of functions or classes. You will be skipping the design/modeling step in these cases.

  1. Understand the problem

    Read the description carefully! Clarify obscure or ambiguous descriptions with your instructor. Estimate the complexity of the whole project and make a time management plan.

  2. Analyze and model the problem (two approaches)

    • use top-down design to break the questions into functions (tasks)

    • use object-oriented design to break the question into classes

  3. Plan your project directory

    Consider the directory structure of the project, the files to create, the makefile to write, etc.

  4. Make a skeleton of the project

    Create all files including cpp files, hpp files, supporting data/configuration files, and a makefile. Fill them with empty functions, empty classes, header guards, know includes, etc.

Implementation Stage

A skeleton repository may be provided for you to use in a GitHub Classroom-based assignment. Run git clone <URL> to clone it to your computer. It may also be provided as a zip file downloadable from Canvas.

  1. Iterative development

    1. Backup your files (three options)

      • best with a version control system like git. Just add and commit using git add -A and git commit -m "commit message"

      • compress the directory and give it a serial number or a date time stamp

      • duplicate the directory and give it a serial number or a date time stamp

    2. Pick a unit to work with

      • start from the simple units first (“simple” means simple in logic and not depending on other units)

      • move on to units depending on finished units

    3. Write code in small units (function, class, class method)

    4. Write a test driver (sometimes provided)

    5. Write rules in makefile to build and run the tests (sometimes provided)

    6. Fix problems found in the run

    7. Proceed to the next iteration

  2. Perform a final test

    • Run all tests locally

    • Transfer your files to the SSH server and test run

Warning

Tests on SSH server is usually only necessary if your environment is not compatible to Linux, such as MinGW, CygWin.

  1. Submission depending on the requirement

    • GitHub classroom submission github-classroom

      Simply git push origin main

    • Canvas file upload

Note

This workflow is designed for C/C++ project but is applicable to projects written in other general purpose languages such as Python and Java. The major difference is that the building system is no longer GNU make. You will be using setup.py, wheel or poetry for Python, and Maven, Gradle, or Ant for Java.

You may learn more about how to write makefiles here: GNU Make.

Canvas file upload

  1. Duplicate your directory

  2. Change the directory to the base name of your submission file like proj#. Substitute # with your project number.

  3. Change to the new directory in your terminal

  4. Remove files not needed in the submission (the make clean command should do most of the job for you)

  5. Perform a last test on everything (local or on the SSH server)

  6. Clean the generated files in the test run using make clean again

  7. Compress your directory using zip format and name it as proj#.zip

  8. Find the Canvas assignment page and upload

  9. Visit the page again to confirm the uploaded file is there

Build, run and debug

Due to the complexity of compiling and running your modular project manually, building tools such as GNU make, Autotools, Cmake, Ninja, Meson are employed to automate the process. We employ GNU make in our course.

Make command-lines

The make command-lines commonly employed in the projects are:

  • make

  • make all to compile multiple targets

  • make main to compile main

  • make test-run to test run your main

  • make test to compile and run a test

  • make test-all to compile and run multiple tests

  • make test-#-xxx to compile and run one of the many tests where # is a number, and xxx is a name of the individual test

You must compile and run your code through these commands because this is how the grader will employ in the grading.

Provided Tests

  • Tests are provided in some starting code bases to facilitate grading.

  • Students are not supposed to change source codes in the test directory or the cpp files provided for test such as test.cpp.

  • Make sure your filenames follows the naming convention so the makefile will work properly. The convention requires all lowercase filenames.

  • Complete the makefile as needed.

  • Run make test or make test-all to run tests.

  • You can find other test-#-xxx kind of targets in your makefile to run tests separately.

  • Make good use of these tests locally to test your code.

  • A major portion of grading will be based on the tests runs.

Note

refer to proj-make.rst for more information on troubleshooting make runs.

Get Help

  • Post sharable problems on the Discord server

  • Email the instructor or TA about the question. Must include your code.

Warning

Never ask me question with only limited information like screenshots or error messages. Push your code to the GitHub server and let me know. If GitHub is not used for projects, attach the zip file of your source code files in your email.

Avoid Common Mistakes

  1. Avoid over-engineering

    • Understand the problem and requirements very well

    • Work toward a just-enough solution (follow the instruction) rather than a perfect solution

    • Choose the simplest (simple to use) data structures, not the fastest or coolest ones (e.g. choose vector over C array, string over C string)

  2. Avoid bad submission

    • Run make clean before add and commit

    • Remove any added files and directories not needed in the submission. They are usually from your editor or IDE and can be huge in size.

  3. Avoid wasting time on anything not required in the instruction

    • Read instruction carefully

    • Ask questions if you are not sure

  4. Avoid last minute rush

    • Projects are usually more challenging than you think

    • You will not learn much in the rush

  5. Avoid writing code without testing

    • Any project beyond a certain size should be finished in an incremental manner and tested in every step

    • In the future, you may want to learn a testing framework but for now tests can be as simple as an extra .cpp file with a main function to run the classes or functions you just finished. Just feed the object/function with some input data and check the output. Testing code should be in a separate cpp file

    • A testing framework (e.g. Catch2) will greatly improve this process but need learning

    • A final test on the SSH server recommended to avoid compatibility problems (not necessary if your code are graded on GitHub)

  6. Avoid working without backing up your code

    • It is common to lose important code snippet by mistake

    • You will hesitate to try new idea

    • Do backup your changes frequently

    • Do keep a log of your progress

    • If possible, using a version control system is the best solution