⚠️ The deadline for this week’s submissions is Tuesday 30.4. at 23:59. You can do the tasks either by yourself or in the exercise sessions.

Return your work by pushing to the GitHub repository which you registered into Labtool. Remember to push your work before the deadline! Any work pushed after midnight will not be taken into account (or will bring 0 points).

The points and feedback will be available before next week’s deadline. Please check your points and feedback. If you get any questions or concerns about the grading, send a message through LabTool.

This week, you can get 3 points from the practical work and 2 points for the code review.

⚠️ During this week there will be a code review, which starts on Wednesday 24.4. at 23:59.

Docstrings and documentation

“Code is more often read than written.” — Guido van Rossum

When you’re going full steam ahead, programming a fancy new project, you may often think that once you’ve written a piece of code, you’ll never have to return to it again. In reality, a piece of code can live in a project for many years, during which you and other developers will have to read and improve on the code you’ve written. It may take a very long time to undertsand some code, especially if it’s messy! Clean code is a good start, but having relevant documentation is just as important.

Documentation using comments

Comments are very useful and are universally accepted. However, code comments have to be relevant to not “stink up” your project with irrelevant commentary. Here is an example of what not to do:

class Machine:
    def __init__():
        self._tank = FuelTank()
        # fill tank with 40 units
        self._tank.fill(40)
        self._engine = Engine(self._tank)

    def drive(self):
        self._egine.start()
        # check if engine is running
        running = self._engine.engine_is_running()

        # if engine is running, use energy
        if running:
          self._engine.use_energy()

A comment should never explain what a single line of code is doing: that should be evident from your variable names. Instead, comments should tell you what an individual module, class, or method/function does on a logical level and what kind of interface it has (that is, what arguments it takes in and what it returns). These types of useful comments are called docstrings in the Python world. There are many different formats for dosctrsings, but in this course we will be using the Google format.

Let’s see how this works with our favourite PaymentCard class:

class PaymentCard:
    """Class that keeps track of the balance on a card

    Attributes:
        balance: The starting balance on the card.
    """

    def __init__(self, balance):
        """Constructor, which creates a new payment card.

        Args:
            balance: The initial balance on the card.
        """

        self.balance = balance

    def add_money(self, amount):
        """Increases the money on the card by the specified amount

        Args:
            amount: The amount of money to be added.
        """

        self.balance += amount

    def take_money(self, amount):
        """Decreases the money on the card by the specified amount

        If the card does not have enough money, the balance is left unchanged.

        Args:
            amount: The sum to take from the card.

        Returns:
            True, if the card had enough money, otherwise False.
        """

        if self.balance < amount:
            return False

        self.balance = self.balance - amount
        return True

    def __str__(self):
        """Creates a text representation of the card.

        Returns:
            String, that tells the balance on the card in euros.
        """

        balance_euros = round(self.balance / 100, 2)

        return f"Balance: {balance_euros}"

Documentation is always done on the line right after the definition of a class, method, or function. Documentation always starts and ends with the """ signs. The first lines cover a general overview of the functionality. With classes, then come the attributes (what variables the class has), which are under a Attributes section. Attributes are written in the format attribute_name: Attribute description. Methods and functions are documented in exactly the same way, except instead of attributes you have arguments (variables passed into the function). These are documented under an Args section instead of an Attributes section. Return values from functions and methods go uner a Returns section. Note the capitalisation and indentation in the example!

If you are using VSCode, you can install the Python Docstring Generator extension. This will automatically generate a docstring template for you when you type """ and press TAB after a function or class definition.

Code review

A maximum of two points can be awarded for the code review.

The purpose of this code review is to learn how to read another person’s code, and how to interpret another developer’s entire project. A career in programming requires you to know how to read code fluently. Unfortunately, reviewing code is not often covered in other courses. A well-done code review is an efficient way to notice problems in your code and improve the code quality.

Do not include the time spent on the code review in your time tracking sheet.

Instructions

The start date of the review is Wednesday 24.4. at 23:59. You will get access to your partner’s code on this date at the latest.

Your task is to read through another student’s assignment and provide constructive feedback. You should also try to run the program.

  • Download your partner’s zipped project to your computer
    • Mark down the date and time when you downloaded the project
    • Unzip the project
    • Instead of downloading the zip from the releases, you can use the git clone <link> command to clone the repository to your computer directly

  • Start by reading the project spec document
  • Read as much of the code and tests as possible
    • Try to also run the tests
  • Try to understand what each class and method does
    • Be persistent: you won’t always know what’s going on, and this isn’t expected of you!
    • The most challenging part is probably the relationship between the classes. Try to read the class diagrams for help

Once you’re familiar enough with the project you’re reviewing, it’s time to give your partner feedback on their code. You do not need to comment about the documentation, appearance or the functionality of the program. The most important thing is to pay attention to the good practices learned in Introduction to Programming and Advanced Course in Programming. Also, make sure that the code satisfies the code quality requirements for this course.

Feedback

The most important thing in the feedback is to tell the author how they can improve their code. The more specific the feedback, the more valuable it is to your partner. You can give tips on how things could be done differently or how you would have implemented something. If you find evident bugs or code that does something unintentional, write about that, too. You should examine the code carefully and provide specific suggestions for improvement. Please also include positive feedback!

Feedback is provided as an issue on GitHub:

  • Go to your partners’ repository in your browser
  • Open the Issues tab
  • Select New Issue from the right-hand sidebar
  • Put “Code Review” as a title
  • Type your feedback in the comment box. You can and should use markdown here for clarity: use the Preview tab to see what it will look like
    • Above the comment box, there is a link to a useful Markdown reference
    • If you have specific code that you want to highlight, you can use Markdown’s code blocks
    • The comment box also supports images
    • To be on the safe side, please copy your feedback to a text file on your computer
  • Include the date and time that you downloaded the project at the beginning of the feedback
  • Submit your feedback by selecting Submit new issue
  • Finally, add a link to your feedback in Labtool

Your feedback is a public GitHub issue, and can be viewed by anyone. The TAs will read and grade your feedback as soon as possible after the deadline.

A score of 0-2 will be assigned for the code review. A minimum of 6 high-quality and constructive feedback comments is sufficient for 1.5 points. Full marks also require at least one usable suggestion for improvement.

Feedback can be written in whatever style you like, but try to write clearly. Split feedback that belongs to different classes and methods into separate paragraphs. If you write in bullet points, write complete sentences or preferably several sentences. Do not attack the other person in your feedback! Similarly, don’t take the feedback you receive personally - your project is still in progress and can be edited. Even the person giving feedback sometimes misunderstands or gives incorrect instructions.

Note: The project you are reviewing may change or be updated while you are writing feedback. Therefore, the feedback should include the time the project was downloaded. This means that you do not have to actively check whether your partner has updated their code: it is okay if your feedback is outdated after the author pushes some changes. Similarly, remember that the feedback you receive may be for an older version that you have already changed.

Practical work

Remember that the end of the course is approaching, and so is the final submission deadline. You should take some time to review the grading criteria. During the last week, you will have time to develop your program, but you should also leave plenty of time for documentation.

This week, you will further expand your project and improve its documentation.

There are 3 points on offer this week for the practical work. Remember that, in addition to your weekly points, you will get points for your final submission based on the criteria.

Practical work 1: New functionality

Expand your project from last week (0.75p):

  • You should be able to run your program using poetry run invoke start
  • The program should be bigger than last week’s version and implement some more functionality that’s in your spec document. That is, your program should include more functionality that’s useful for the user.
  • Mark the features that you have implemented as “done” in your spec document.
  • After you are done, create a release in GitHub again.

Implementation instructions can be found here.

Practical work 2: Tests

Expand the tests (0.5p):

  • You must be able to generate a coverage report for your code using poetry run invoke coverage-report
  • There must be a .coveragerc file in your project’s root directory, which defines which directories are included in the report. You must leave out the UI and tests from the coverage report.
  • Remember to include an empty __init__.py file in each subdirectory under src
  • The branch coverage must be at least 60%
  • The tests should test something relevant to the functionality of your program

Practical work 3: Code quality

Pay attention to the following (0.5p):

  • The program should not have lots of copy-pasting or repetition in it
  • The program structure is reasonable
    • Classes, methods, and functions should follow the single responsibility principle, i.e. one component cannot do too many things
    • Classes, methods, and functions that are too big should be split into bits
  • Keep in mind the usual code quality requirements

Practical work 4: Documentation

Begin writing docstring documentation for your project (0.5p):

  • To get the points, at least half of your classes, methods, and functions have docstrings
  • Tests do not need docstrings

Create a preliminary architecture description (0.5p):

  • The document should contain a high-level overview (e.g. what file does what) of your program structure and program logic
  • You may use the previous weeks’ class and sequence diagrams
  • You may take inspiration from the reference project
  • A good length for this week is 1-2 pages of text and diagrams

Create preliminary usage instructions (0.25p):

  • The instructions can assume that the code will be run by hand, so you do not yet need to include installation/configuration instructions
  • A good length for this is about one page
  • You may once again take inspiration from the reference project

Practical work 5: Changelog

Document the significant changes you make during this week in the changelog.md file, which is in the dokumentaatio folder. You can see an example in the reference project.

Note: Forgetting to do the changelog will result in a significant point reduction.

Practical work 6: Point reductions

Forgetting to do the following things will result in points being deducted:

  • Code quality
    • The structure makes sense (e.g. having all of the code under the same directory)
    • The program logic is separate from the UI
    • Pylint is in use
      • There are less than 5 pylint errors
      • UI and test code can be left out of linting
  • The time tracking sheet is up-to-date
    • You must sum up your hours and mark the total in your file
    • Do not include the time spent on weekly exercises (before week 4)
  • There is a changelog entry under changelog.md
  • The README.md file is proper
    • The file must have the same structure as that in the reference project, i.e.:
      • Short description of your project
      • Links to the spec document, architecture document, user instructions, and time tracking sheet
      • Link to your releases
      • Instructions on how to run your project (running your code, running tests, generating coverage report, linting)
  • The repository is clean
    • No extra garbage (e.g. output from the pytest or coverage commands)
    • Weekly exercises must be under laskarit
    • There is a relevant .gitignore
  • Docstring documentation has been started

Make sure the project works as intended

NOTE: In order to receive weekly points for the assignment, the application must work on the university’s computer and the TAs must be able to run your code on them! You can test this on any Cubbli computer, such as the freshers’ laptop, or on the computers in your institution’s computer classes. You can also test on a virtual workstation using either a browser or the VMWare Horizon client.

In the virtual workstation, testing of your own application can be done using the browser as follows:

  1. Log into virtual workstation and select Cubbli Linux
  2. Start the terminal and check the version of Python in use with the command python3 --version. If the version is below 3.8, update the version using the instructions here
  3. Make sure that Poetry is installed by running poetry --version. If the installation is missing, follow these Linux installation instructions
  4. Clone your repository to the directory of your choice using the git clone command
  5. Go to your project’s directory and install the dependencies using the poetry install command. Note that the command must be run in the directory where the pyproject.toml file is located.

If the connection to the virtual workstation fails, you should try another browser. Users have reported that at least Google Chrome works quite well. Installing VMWare Horizon Client may also help.

Note: If you are running an application which uses an SQLite database on a virtual desktop, you may encounter the error database is locked. You can probably fix the issue by following these instructions.

Plagiarism

The course follows the University of Helsinki’s study policies Plagiarism and academic plagiarism, i.e. copying answers from the internet or from a friend and returning them as your own work is forbidden. A proven case of plagiarism will result in the failure of the course and repeated cases of plagiarism may result in the suspension of the right to study.

What does plagiarism mean in the context of the practical work? Direct copying of code is prohibited, with the exception of short snippets of code and code generated by ChatGPT or similar tools (see below). Direct copying of code structure, e.g. by changing the names of variables and functions, also counts as plagiarism. On the other hand, you may use images found on the web if you have the right to do so (see below), but if you do so, you must include a reference to it in the documentation of the work, i.e. mention where the quotation was made.

The same plagiarism rules apply to the documentation of the work and it is particularly forbidden to copy-paste the documentation of a reference project.

ChatGPT and similar

Representing code or text generated by ChatGPT and similar AI-based tools (such as Bing Chat, Google Bard or GitHub Copilot) as self-plagiarism is also plagiarism. The use of generated code is allowed in the course, but always “surround” such code with the comments # AI-generated code begins and # AI-generated code ends. Do this even if you have made minor changes to the generated code (changing the names of variables and functions, etc.).

Remember that the use of ChatGPT and similar tools for generating tests is prohibited in the course.

Copyright

Please respect copyright and other intellectual property rights. Remember that you may not use anything found online for your own work. This applies to a wide range of material from software code to images and texts. So always check whether use is permitted under the licence under which the material may have been distributed. Remember that your work is public by default on GitHub. It is your own responsibility not to infringe copyright.