⚠️ The deadline for this week’s submissions is Tuesday 16.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, returning the practical work yields 3 points.

Pylint and analysing your code quality statically

In addition to writing tests, taking care of your code quality is important. This can be done manually by, for example, documenting quality requirements or via a code review. However, for bigger projects, manual review is impractical. Instead, we can use static analysis, where your code’s quality is analysied automatically without running it. Static analysis is widely used for quality assurance and for noticing mistakes in programs. For Python code, the pylint library is perhaps the most popular. Using pylint, one can set up requirements for your code quality, and the program will check these automatically.

Pylint is a tool that checks for errors in Python code, tries to enforce a coding standard and looks for code smells. It can also look for certain type errors, it can recommend suggestions about how particular blocks can be refactored and can offer you details about the code’s complexity.

Using pylint in your software

Pylint is very simple to use in a Poetry project. We begin by installing it as a development dependency:

poetry add pylint --group dev

You then give pylint a set of rules that it must follow. The rules are defined in a .pylintrc file, which is located in the root of your project. Create this file and copy the contents of this file into it. These contents differ slightly from the default ones, that you would get by running pylint --generate-rcfile.

To run the checks, open the poetry shell by running poetry shell in your terminal. After this, you can run pylint’s quality checks by running pylint src. You must run this command in the root of your project (i.e., the same folder where pyproject.toml is located). Pylint will output a score for your code.

Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

Turning off quality checks

Generally, you should aim to fix the issues that pylint tells you about. The vast majority of the time, this will result in better quality code. Occasionally, though, we can accept the dips in code quality and turn off some checks. There are multiple ways to do this.

Let’s take the following src/index.py file as an example:

x = 3
print(x)

Running pylint src, we notice that it complains about the following:

src/index.py:1:0: C0103: Constant name "x" doesn't conform to UPPER_CASE naming style (invalid-name)

Pylint thinks that in the src/index.py file, on line 1, the variable x should have been named X since it’s a constant. We could just fix the issue and be done with it, but if for whatever reason you do not want to do that, you can also add a comment after the line:

x = 3 # pylint: disable=invalid-name
print(x)

Now, pylint src reads that you want to ignore the invalid-name error for that line and no longer complains.

You can also turn off linting for entire files and folders. Try modifying this row in the .pylintrc file. We can, for example, leave out the UI code located in src/ui and the tests under src/tests by adding the following:

ignore=CVS,ui,tests

In your project, do not turn off linting for anything but UI features and tests!

Fix all the issues that pylint notices in your project code. There are very few cases where turning off linting is actually a good idea.

Integrating pylint into VSCode

If you have Visual Studio Code in use, you can simply check that the Python addon is installed. You may also need to install the Pylint addon.

Visual Studio Code Python addon

One the addons are installed, VSCode will tell you about pylint’s detections automatically by underlining them in red. By hovering your mouse over the problematic code, you can get some more information on the error:

Visual Studio Code pylint

If you encounter issues with this, take a look at VSCode’s linting instructions.

Automatic formatting

The most popular style guide for python is PEP 8. This guide tells you how to, for example, use whitespace, indentation, variable naming, line length, etc. to make your code look pretty. While it is important that you follow these instructions, it is quite tedious to fix all of your code manually. Thankfully, there is a module that will automate this process: autopep8.

To install autopep8, run:

poetry add autopep8 --group dev

After this, launch the poetry shell and run the follwing in the src directory:

autopep8 --in-place --recursive src

You can also make an Invoke command for this, so that you can run autopep8 with the command poetry run invoke format.

In addition, you can do this with one button press directly in VSCode by following these instructions.

Common issues

  • If pylint complains that pygame has no X member, you should open the .pylintrc file and change the row extension-pkg-whitelist to say extension-pkg-whitelist=pygame.

Practical work

During this week, you will implement new functionality for your program, improve documentation, and pay attention to your code’s quality using linting.

There are 3 points on offer from this week’s practical work submission. You should also take a look at the assessment criteria for your project, which will be used to give points to your final submission.

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.

Implementation instructions can be found here.

Practical work 2: Testing

Add more tests to the program (0.5p):

  • You should be able to create a coverage report for your program using poetry run invoke coverage-report
  • In the root folder of the project, there should be a .coveragerc file, which defines what files are included in the report. Any functionality related to UI and tests should be excluded from coverage reporting
  • In your src folder (and all the folders under it, and all the folders under those…) there should be an empty __init__.py file, so that the test coverage report works.
  • The branch coverage must be at least 20%
  • The tests should test something relevant related to your functionality

Practical work 3: Code quality

Pay attention to the following things related to code quality (1p):

  • The program logic should be separate from the UI code
    • Find some hints here and in the reference project
    • For example, the UI components and the program logic should be in separate files
  • The program structure should be logical and be named properly
  • Pylint should be in use
    • Use this .pylintrc file
    • You will get full points for this part if there are fewer than 10 pylint errors
    • You may leave out the UI and test files from linting
    • You may not use pylint: disable comments without a well-justified reason
    • You must be able to run the pylint tests using an Invoke command, poetry run invoke lint

Practical work 4: Documentation

Create a class diagram or package diagram to describe your (preliminary) program structure (0.75p):

  • Your diagram should just show the classes relevant to your program logic
  • If you want, you may also include a package structure diagram
  • You can find an example in the reference project
  • Add a file called arkkitehtuuri.md under the dokumentaatio folder in your project, and insert the image into the file. The rest of the file can just be empty
  • Include a link to the arkkitehtuuri.md file in the README.md file, similarly to how it’s done in 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:

  • The time tracking sheet is up-to-date
    • There must be a sum of total hours used
    • You should not include the time spent on the weekly exercises in weeks 1-3
  • There is a changelog entry for this week in the changelog.md file
  • The README.md file is professional
    • The file should have the same structure as the reference project’s README.md file, excluding the information that hasn’t been covered or implemented yet
    • All extra information, such as links to the weekly exercises, have been removed
  • The repository is clean
    • No extra trash (e.g. the output files of the pytest and coverage commands)
    • All weekly exercises are under laskarit
    • There is a reasonable .gitignore file

Extra code review

There is going to be a code review on week 6. The point is to give feedback on someone else’s work. This is useful for both the author of the code and the one reading it. If you want, you can already do a code review on weeks 4 and 5, if someone else agrees to give you their code to review. This is completely optional and extra, but you can get an extra course point for this (added to the points in week 5).

If you want to do a code review:

  1. Go to the Moodle page and see if there are any projects under the “Ylimääräinen koodikatselmointi” section that are not yet reserved. If you can find one, write your name after it to reserve it. See what topics the author wants feedback on.
  2. Use the code review instructions to give your feedback as GitHub issues. For the extra code review, two high-quality and constructive comments and one improvement suggestion are enough. These should include comments on any questions that the code author may have asked. Instead of having “Code review” as a title, put “Extra code review” as a title.
  3. Go to your own project’s README.md file and add a bolded line of text saying “Extra code review” and a link to your review at the bottom.

If you want your code to be reviewed: Go to the Moodle page and add a link to your repository under “Ylimääräinen koodikatselmointi”. After the link, write a question or topic that you want feedback on from the reviewer.

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.