Homework I

RequirementsVariant generator

For homework I, you have to write a program based on the set requirements and document the results. The focus of this homework is in the correct use of files and structures alongside with common practices such as dividing code and command line arguments. Some variants will benefit from enums.

Requirements for the program

The code must adhere to all of the best practices introduced during Programming 1 and the first weeks of Programming 2.

Your solution can include topics that have not been covered, as long as they are used correctly and well documented. You need to provide motivation why those concepts were used so that it clear, that you have mastered those topics.

Requirements for the standards and environment

The program must be written in the C programming language. You are permitted to use the C90 and C99 standards. Upon an agreement, you can also use newer standards such as C11 and C17.

In addition to using the standard C libraries, you are allowed to use C POSIX and GNU C librares. Any libraries outside of this must be agreed upon separately.

Your program will be compiled and tested in a Linux environment, equivalent to the one in the lab computers (e.g. OpenSUSE SLED-15 SP5 or Ubuntu Linux 24.04 or later, using GCC-13 compiler). The software does not need to be compatible with other operating systems such as Windows or MacOS.

General requirements for the solution

  • The source code has to be divided into more than one file. Exact number of files is and their division left to the author of the solution.
    • At minimum, a source and a header file must be presented
    • If multiple .c files are used, a Makefile must be provided to compile the solution
  • The program must accept the name of the input data file as a command line argument
    • The behavior, when the argument with the name of the file is not provided or the file could not be opened, is up to the developer. Chosen behavior must be documented!
    • You can write the handling of command line arguments manually or use  unistd.h  or argp.h  libraries for parsing.
  • Te result of the program must be shown both on the screen and saved in an output file
    • The output file will only contain the results of the program
    • The results of the program must also be presented on the screen. You are allowed to be more verbose in your terminal output, include interim results  and additional relevant information, confirmations, prompts for input etc.
    • The output needs to be clear and understandable
    • The name of the output file is left to the developer
  • The program must work with data files where the length of the file is not predefined. Adding or removing some lines from the data file should not cause any issues
    • Defining the maximum number of lines the program can handle is allowed. If there are more entries in the data file, reading them is not necessary.
    • There is no need for dynamic memory allocation -we will cover that in the next homework. You are still allowed to use it, if you handle it properly (only allocating for what you need, checking the allocation, freeing the memory etc).
  • The data is read from the input file and stored in a struct  array. The task description may also require use of nested structures. You are free to add additional members and nested structures to the solution. You can also add additional structs, if it makes sense for the solution. NB! This does not mean you can add values to the data file!
  • The program must provide basic user experience (UX)
    • The program must notify the user of any errors encountered in a clear manner. The message must be precise and helpful to the user to solve the issue. All error messages must be written to the stderr  standard stream.
    • When user input is expected, the prompt must be clear to the user. If the input needs to be in a specific format, you must provide the user with the expected format. If applicable, add an example of how the input should be written.
    • If the program contains searching, filtering or grouping features and there are no matches the set criteria, it must be written explicitly to the user.

Input data file requirements

  • The data file must only contain fields described in your task variant (nothing extra, none skipped)
  • Data model for the input file is created by the author of the solution based on their capabilities and knowledge. This includes data field delimiters, order of data fields, data field contents,  complexity,  etc. The chosen data model and the decisions for it are documented by the author in the document provided alongside the program.
  • The data records will be created by the author of the solution and submitted with the solution. The data file must contain at least 10 entries. If the author of the work presents multiple data files for demonstrating different scenarios, the length requirement only applies to one of the data files.

Documentation template

Use the same templates as you used in Programming 1, Homework 1 (https://blue.pri.ee/ttu/programming-i/homework-i/) and adjust it to fit the requirements of this homework.

Documentation requirements

Note: the length of the document’s written part (includes input file structure, detailed description of the solution and how-to guide) should be in between 3 – 6 A4 pages.

Focus on structured documentation!  Avoid story-telling (except summary).

  • Title page
  • Declaration of originality
  • List of abbreviations and terms (if needed)
  • Table of contents
  • List of figures and tables (if needed)
  • The task description (variant)
  • Detailed description of the solution (no walls of text!)
    • A brief description of what the program does
    • Program workflow – In what order are things done? (Do not go into details! Half a page maximum!)
    • Document the structures (for each structure)
      • Purpose of the structure
      • For each member, their name, data type and description
    • Special situation / error handling
      • Description of issue
      • What’s the status of it – did you solve it, work around it, is it still present in the code
      • If it was mitigated, how did you mitigate it
  • Data file structure
    • Structure of one record (data field order, separators between fields, separators between records
    • Data fields – name, data type, example of a value, meaning of data (semantics), any limitations (e.g. length, value range, illegal values)
    • Present a single data record from the file as an example.
  • How-to guide for using your program. Describe all options that can be used regarding command line arguments.
  • Extra task (if you solved the extra task)
  • Summary
    • Write a few sentences about your approach to the task and progression during it
    • Write a few sentences about the task itself and the complexity of it
    • If possible, give an estimate on the workload
    • Would you recommend using this task in the future? Would you change anything about it and if so, what?
    • Additional comments, emotions, thoughts
  • References (can be omitted if not present)
  • Screen capture(s) of the program
    • Screenshots can be added as an appendix or embedded within the write up of the solution – in this case you can extend the length by the amount of pictures
    • The screenshots should show both normal operation and operation in various error situations

Extra task for bonus points

It is possible to earn up to 2 bonus points from the task. In order to get any points, you must include the added features to the report. It is possible to obtain partial bonus points if not all requirements are met.

To get bonus points, the following requirements must also be met in addition to the basic ones:

  • Comprehensive support for command line arguments
    • It must be possible to use the program without command line arguments, using default values.
    • Must support use of a different input file name
    • Must support use of a different output file name
    • Must support disabling printing on the screen
    • Must support disabling writing the output to the file
    • You must figure out a reasonable way to allow for the use of these options – this includes allowing for multiple options to be used at the same time.
  • The program must hold the default values in a separate configuration file, provided with the solution. During the execution of the program, the settings are to be kept in a separate struct  dedicated for settings.
    • At minimum, the configuration file needs to hold the name of the input and output files and output settings (output to the terminal enabled, output to the file enabled)
    • The values in the settings file are used when no command line arguments are provided
    • If any of the values are passed using command line arguments, they will be used in place of the value in the settings file (e.g. if the name of the input file is provided, it will be used for the input, but all other settings are taken from the settings file).
  • Must have reasonable effort made to avoid problems from a broken / corrupted data file – e.g. illogical values, incorrect data type and other oddities
  • You must add a level 1 heading to the documentation called “Extra task”.
    • Describe the added features
    • Describe your thought process on how you chose the functions
    • Describe the chosen input sets and why they were chosen

Before submission checklist (common mistakes, oversight)

  • The name of the data file in the code is the same as the data file you are uploading to Moodle, data file requirements are met
  • Documentation is well structured and includes the required topics. Requirements for writing documentations are followed (figures are captioned and cross-referenced, heading styles are correct, all headings are followed by text of at least three sentences etc).
  • Your code has basic error handling and clear user experience
  • The program is divided into small and meaningful functions
    • All functions are preceded by a comment (description, parameters, return)
    • Data moves to and from functions using parameters and return values. Global variables are NOT permitted (except when they are in a separate library, ask for details if interested)
  • The proposed coding style for the subject is used. Alternatively, you can use widely accepted coding styles for C programming such as Linux Kernel coding style.
    • The code is properly indented, whitespace and newlines are used where needed to guarantee good readability
    • Code is commented. This includes the comment in the top of all code files, as well as before all functions (except main)
    • Naming of functions, variables, macros, … is clear and self-explanatory as to what they hold.
    • The coding style is consistent throughout the work.
    • No magical numbers
    • etc.

Deadlines

A complete homework must be submitted no later than 16.03.2025 23:59:59 (local time)

Each week passed the homework deadline will deduct 1 point from the final homework score. The late penalty is capped at 5 points, meaning if you submit 7 weeks late, you will still lose 5 points..

If we have questions about the submitted homework or are not sure about the original author of this work, we will grade this with 0p. In this case, the work must be defended.

If it becomes necessary, we will enforce the rules and guidelines of [Procedure for processing a student’s violation of academic practices and contemptible behavior in the School of Information Technologies]

We will only accept Your homework until the lockdown date (check introduction slides). Past that, submitting your homework will not be possible.

Submitting

The homework needs to be submitted in the Moodle course under Homework 1.

Files required:

  1. Documentation (pdf)
  2. All of the code files (.c and .h) to compile the program. If multiple files are used, a Makefile is also required.
  3. Data files required to run the program

Naming schema: HW1_<firstname>_<lastname>_<studentcode>

Example:

HW1_Heli_Kopter_123456IASB.c
HW1_Heli_Kopter_123456IASB.h
HW1_Heli_Kopter_123456IASB_documentation.pdf
HW1_Heli_Kopter_123456IASB_data.txt

You are allowed to submit the code files and input files as a .zip archive. Tthe PDF document must be uploaded separately, next to the zipped archive! I.e. HW1_Anti_Tiib_112211IACB.zip ja HW1_Anti_Tiib_112211IACB_documentation.pdf

Result and feedback

After your work has been checked and graded, you will see the result and feedback on Moodle (visible from your gradebook only!). If everything was well done, feedback may be absent.

Fixing your homework

You are allowed to fix and improve your homework score until the date of homework lockdown. All fixed submissions are subject to defense.

To fix your homework, first go through your feedback. Then contact your teacher and agree upon the process of how this homework can be fixed.

NB! If fixing the homework changes more than half of the original homework, it is considered as submitting a completely new homework, from which minus points can be deducted from depending on the time of submission.