Skip to content

The student's guide to clean code development

Jump to bottom
jose-antonio-torres edited this page Jan 27, 2023 · 20 revisions

Welcome to the student's guide to clean code development using GitHub! This page aims to set a clear path so that, once you have completed all the tasks, you will have all the tools you need to develop high-quality code for Swan.

Note: this guide was originally written for students enrolled at UPC's ESEIAAT, coursing either GRETA or GREVA. If you are not enrolled there, this guide may also be useful for you -- just replace the "Estructures Aeroespacials" code for some other code you have developed and you will be set!

Task 1 - Setting up the tools

Description

The goal of this week is to do your first steps. It mostly involves setting up the tools you will be working with, so it is important that you take your time to gossip around. You will learn how to:

  1. Set up your GitHub account and GitHub Desktop
  2. Create your first repository using code you have previously written.

To-do

Create a small report (perhaps as a MATLAB live script) showing what you have done.

  1. Get familiarized with GitHub. Look around the "Code" and "Pull requests" tabs. Briefly explain what GitHub is and what it is used for.
  2. Explain the differences between GitHub and Git.
  3. Create a GitHub account and install GitHub Desktop. Create a repository of the code you developed in the Estructures Aeroespacials subject. Include a screenshot of GitHub Desktop's interface, as well as a link to your repository.
  4. Take a look at the basic Git commands and see how they are implemented in GitHub Desktop. List which actions cannot be performed using GitHub Desktop. Explain the differences between committing and pushing.
  5. Include a screenshot of GitHub Desktop where you have committed (but not yet pushed) a change, and where you have changed two files, but those changes are not yet commited.
  6. Create a branch of your repository. Make some small changes while in this branch and push them. Open a pull request, and include a link it.
  7. Explain any difficulties that you have encountered in the process

NOTE: This picture may help you to understand the different kind of work flows present during clean code development.

Task 2 - Object-oriented programming and clean code in MATLAB

Description

This week you will learn about:

  1. Object-oriented programming in MATLAB
  2. Clean coding practices in MATLAB

It is important that, when you develop any code, you follow the guidelines that had been put in place by previous developers in order to ensure coherence. Since Swan uses object-oriented programming and clean code, it is important that you take time to familiarize yourself with these concepts.

To-do

Create a small report showing what you have done.

  1. Research what the object-oriented programming is, and compare it with other programming paradigms. Explain the fundamentals of OOP.
  2. Explain what composition and inheritance are. Explain why using composition is preferrable over inheritance.
  3. Explain what the different types of data access are. Explain why favoring private properties and methods is considered a good coding practice.
  4. This code and this code perform similar actions, but the second follows an object-oriented approach. Explain the difference between the private methods in lines 31-75 and the method in line 81 (hint: look at lines 29 and 79).
  5. Take a look at this class, this class and this class. List all the design patterns that you notice, as well as any clean code practices you find.
  6. Time to create your first class and include it in the code:
  • The goal is to replace the lines which compute the global stiffness matrix.
  • These lines will be replaced by the GlobalStiffnessMatrixComputer class, which will take four arguments: the matrix of elemental stiffness matrices Kelem, the nodal connectivities matrix Tnod, the number of nodes and the number of degrees of freedom at each node.
  • Create and use previous class in your code to compute the global stiffness matrix.
  1. Time to go one step further and create the following set of classes to include in the code:
  • The goal is to replace the line which calculates the displacements uL at the free nodes, which is located in your your solve system function.
  • It will be replaced by the Solver class, which will take two arguments: a generic LHS matrix and a generic RHS vector, such that LHS · x = RHS
  • Create a DirectSolver class with a function that solves the system of equations directly.
  • Create an IterativeSolver class with a function that solves the system of equations iteratively, using MATLAB's pcg function.
  • Create a Solver class. This class will act as the parent class of the two solvers that you have previously created. Implement a method to create either a Direct or an Iterative solver, using a simple switch structure.
  • Use this Solver class in your code to calculate uL.
  1. Push the changes and include a link to your commit. Remember to explain any hurdles you have found along the week!

Task 3 - Test-driven development

Description

An important aspect of Swan is that tests are the main driving force of the development. Setting up benchmark cases as tests and then ensuring that this code always passes these tests is Swan's bread and butter. Also, you have already seen that the development of Swan occurs in GitHub, which uses Issues and Projects to help push development. This week you will:

  1. Learn about unit testing
  2. Set up your own tests
  3. Create some Issues and Projects for your repository

To-do

  1. Before you start, take a look at the rest of the tasks. Using GitHub, create a Milestone for this task, and Issues for the rest of the bulletpoints of this task. After that, create a Project and reflect the progress you make during the week there as you complete the various tasks.
  2. Explain what unit testing is, and why it is useful to devote some time to create such tests.
  3. Create the first test for your code: ensure that the stiffness matrix has been assembled properly.
  4. Create more tests for your code:
  • Create a test to check that the total force coincides with the expected value
  • Create a test to check that the displacements have the expected value using a Direct and an Iterative solver.
  • If you want to cover additional parts of the code, feel free to add more tests and explain why you added them.
  1. Run a code coverage analysis within MATLAB using the tests you have created (use Run> Run and time). Include a screenshot of the analysis and comment on the results you have obtained: are they good enough?

Task 4 - Code refactoring

Description

It is time to put into practice what you have been learning these past weeks. This week you will

  1. Learn about code refactoring
  2. Refactor your own code This task is complex and will probably take some time -- do not worry, it is normal. Sharing your thoughts, problems and ideas with your supervisor is more than encouraged!

To-do

  1. Refactor the tests you had previously created so that they follow an object-oriented approach.
  2. Refactor your Estructures Aeroespacials code to follow an object-oriented approach. Ensure that all tests still pass.
  3. After an initial refactoring, work on applying clean code practices to ensure readability and maintainability. Link some commits, and highlight which clean code practices you have applied.
  4. Explain which strategy you followed to refactor the code, which roadblocks you hit and how you overcame them.

Task 5: UML of your Object-Oriented code. Part 1

Description

During the following two weeks you will learn how to analyze the sequence of any code using Matlab and also to represent this logical relationship with a UML diagram. More specifically, you are requested to:

  • Get introduced in UML modeling.
  • Understand how the sequence of any code is analyzed with Matlab.
  • Represent graphically the sequence of your Object-Oriented code, using the Unified Modeling Language tool diagram.

To Do

  1. Write a small report in PDF explaining with your own words the following topics:
  • Definition of the Unified Modeling Language.
  • Explanation of the differences between composition, association and inheritance, and how each link is graphically represented.
  1. Make a neat copy of your first UML diagram of your Estructures Aeroespacials code and present the final result in a PDF file.
  2. Write a small report in PDF explaining the main difficulties that you have encountered during this task.
  • Speak with your mentor and review your first UML.

Hints:

  • Use the step-in button while debugging your code.
  • Use the Lucidchart software for your UML modeling.

Task 6: UML of your Object-Oriented code. Part 2

Description

In this week you will be continuing the learning process of how to analyze and represent any code with the UML model. Previous work carried out last week will be improved. More specifically, you are requested to:

  • Understand how the sequence of any code is analyzed with Matlab.
  • Represent graphically the sequence of your Object-Oriented code, using the Unified Modeling Language tool diagram.

To Do

  1. Write a small report in PDF with your first UML diagram improvement points discussed with your mentor in previous task.
  2. Refactor your code, based in the improvement points, and show a screenshot of the refactoring commit.
  3. Make a neat copy of your improved UML diagram of the Estructures Aeroespacials code and present the final result in a PDF file.
  4. Write a small report in PDF explaining with your own words and opinion the advantages and disadvantages of UML modeling.

Hints:

  • Use the step-in button while debugging your code.
  • Use the Lucidchart software for your UML modeling.

Task 7: UML of FEM code in Swan repository

Description

In this week you will use the concepts previously learnt regarding UML modeling, applied to the Swan repository's code. At this point, you are familiar with the basis of Object-Oriented Programming and how your first OOP code works. Nevertheless, the UML tool will allow you to understand efficiently how other people's code work. More specifically, you are requested to:

  • Understand how the sequence of FEM code (inside the Swan repository) is analyzed with Matlab.
  • Represent graphically the UML diagram of the FEM code.
  • Explore also the post-processing features of the code.

To Do

  1. Make a neat copy of your FEM UML diagram and present the final result in a PDF file.
  2. Present several pictures of your FEM results, post-processed with GiD software (displacements, stresses and strains). You can use the same problem as the one used for the UML.
  3. Write a small report in PDF explaining the main difficulties that you have encountered during this task.

Hints:

  • Open the Task7.m matlab file, located in the Swan/Wiki folder. Insert a debug point in line 11 and run the code.
  • Use the step-in button while debugging your code.
  • Use the Lucidchart software for your UML modeling.
  • Add the line "fem.print(file)" inside the Task7.m file to obtain the .res files (necessary to post-process the results in GiD).

Task 8: UML of Topology Optimization code in Swan repository

Description

In this week you will consolidate the concepts previously learnt regarding UML modeling, applied again to the Swan repository's code. More specifically, you are requested to:

  • Understand how the sequence of Topology Optimization code (inside the Swan repository) is analyzed with Matlab.
  • Represent graphically the UML diagram of the Topology Optimization code.
  • Explore also the post-processing features of the code.

To Do

  1. Make a neat copy of your Topology Optimization UML diagram and present the final result in a PDF file.
  2. Present a picture of your TopOpt result, post-processed with GiD software (design variable). You can use the same problem as the one used for the UML.
  3. Write a small report in PDF explaining the main difficulties that you have encountered during this task.

Hints:

  • Open the Task8.m matlab file, located in the Swan/Wiki folder. Insert a debug point in line 9 and run the code.
  • Use the step-in button while debugging your code.
  • Use the Lucidchart software for your UML modeling.
  • Set the printing variable to true inside the input file of your TopOpt problem to obtain the .res files (necessary to post-process the results in GiD). You may test both MACRO and MICRO problems.

Custom sidebar example

Clone this wiki locally