From 5897d45c82f2ceba3ec54c52956a6e0f8903eb49 Mon Sep 17 00:00:00 2001
From: damithc Go to the main website [http://se-education.org/guides] Go to the main website [http://se-education.org/guides] This is a sub-project of the se-education.org.
Suggestions, questions, and bug reports can be posted in our issue tracker. Alternatively, contact project mentor Damith C. Rajapakse.
- This work is released under the MIT OSS license. PRs to improve/add content are welcome. This website uses MarkBind documentation tool. This document has some guidance on how to use it when updating contents. Follow the Markdown style guide in your PR. The Guides for SE student projects »
Guides for SE student projects »
Guides for SE student projects »
About Us
Contact
License
Contributing
Acknowledgements
favicon.ico
is based on an icon made by Dave Gandy from www.flaticon.com
This work is released under the MIT OSS license.
PRs to improve/add content are welcome.
This website uses MarkBind documentation tool. This document has some guidance on how to use it when updating contents.
Follow the Markdown style guide in your PR.
The favicon.ico
is based on an icon made by Dave Gandy from www.flaticon.com
Noticed any bugs/issues or unclear areas while following this tutorial? Help us improve it by reporting it at our issue tracker.
Noticed any bugs/issues or unclear areas while following this tutorial? Help us improve it by reporting it at our issue tracker.
We recommend using java.util.logging
package for logging.
Logging Levels
SEVERE
: A critical problem detected which may cause the termination of the application.WARNING
: Can continue, but with caution.INFO
: Information showing the noteworthy actions by the App.FINE
: Details that is not usually noteworthy but may be useful in debugging e.g. print the actual list instead of just its size.We recommend using java.util.logging
package for logging.
Logging Levels
SEVERE
: A critical problem detected which may cause the termination of the application.WARNING
: Can continue, but with caution.INFO
: Information showing the noteworthy actions by the App.FINE
: Details that is not usually noteworthy but may be useful in debugging e.g. print the actual list instead of just its size.AddressBook-Level3 (AB3) is a brownfield project template used by SE courses. Given below are some tutorials to help students understand how to navigate and modify the existing AB3 codebase.
Person
class.Authors:
AddressBook-Level3 (AB3) is a brownfield project template used by SE courses. Given below are some tutorials to help students understand how to navigate and modify the existing AB3 codebase.
Person
class.Authors:
Noticed any bugs/issues or unclear areas while following this tutorial? Help us improve it by reporting it at our issue tracker.
Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write.
— Robert C. Martin Clean Code: A Handbook of Agile Software Craftsmanship
When trying to understand an unfamiliar code base, one common strategy used is to trace some representative execution path through the code base. One easy way to trace an execution path is to use a debugger to step through the code. In this tutorial, you will be using the IntelliJ IDEA’s debugger to trace the execution path of a specific user command to:
(a) learn how to use a debugger to trace code, and
(b) get a preliminary sense of how AB3's code works.
Before we jump into the code, it is useful to get an idea of the overall structure and the high-level behavior of the application. This is provided in the 'Architecture' section of the developer guide. In particular, the architecture diagram (reproduced below), tells us that the App consists of several components.
It also has a sequence diagram (reproduced below) that tells us how a command propagates through the App.
Note how the diagram shows only the execution flows between the main components. That is, it does not show details of the execution path inside each component. By hiding those details, the diagram aims to inform the reader about the overall execution path of a command without overwhelming the reader with too much details. In this tutorial, you aim to find those omitted details so that you get a more in-depth understanding of how the code works.
Before we proceed, ensure that you have done the following:
Noticed any bugs/issues or unclear areas while following this tutorial? Help us improve it by reporting it at our issue tracker.
Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write.
— Robert C. Martin Clean Code: A Handbook of Agile Software Craftsmanship
When trying to understand an unfamiliar code base, one common strategy used is to trace some representative execution path through the code base. One easy way to trace an execution path is to use a debugger to step through the code. In this tutorial, you will be using the IntelliJ IDEA’s debugger to trace the execution path of a specific user command to:
(a) learn how to use a debugger to trace code, and
(b) get a preliminary sense of how AB3's code works.
Before we jump into the code, it is useful to get an idea of the overall structure and the high-level behavior of the application. This is provided in the 'Architecture' section of the developer guide. In particular, the architecture diagram (reproduced below), tells us that the App consists of several components.
It also has a sequence diagram (reproduced below) that tells us how a command propagates through the App.
Note how the diagram shows only the execution flows between the main components. That is, it does not show details of the execution path inside each component. By hiding those details, the diagram aims to inform the reader about the overall execution path of a command without overwhelming the reader with too much details. In this tutorial, you aim to find those omitted details so that you get a more in-depth understanding of how the code works.
Before we proceed, ensure that you have done the following:
./gradlew check
-- all tests should pass.As you know, the first step of debugging is to put in a breakpoint where you want the debugger to pause the execution (e.g., to debug an issue with data saving, you might put a breakpoint in the method that saves data). When using the debugger to trace the code (to learn how it works), we start the same way, by putting a breakpoint in the code where we want to start tracing the execution path.
In our case, it's natural that we start tracing the code at the point where the App start processing user input (i.e., somewhere in the UI component), and then trace through how the execution proceeds through the UI component. That is the part of the UI
component's activation bar indicated by the yellow circle in the component-level sequence diagram below.
However, the execution path through a GUI is often somewhat obscure due to various used by GUI frameworks. Therefore, let us skip that part of the execution path for now, and put the breakpoint where the UI
transfers control to the Logic
component.
According to the sequence diagram, the UI
component yields control to the Logic
component through a method named execute
(also indicated by the yellow circle in the diagram above). So, let's put our breakpoint in the execute
method of the Logic
component.
Searching through the code base for an execute()
method that belongs to the Logic
component yields a promising candidate in seedu.address.logic.Logic
, as shown below.
Intellij Tip: The 'Search Everywhere' feature can be used here. In particular, the 'Find Symbol' ('Symbol' here refers to methods, variables, classes etc.) variant of that feature is quite useful here as we are looking for a method named execute
, not simply the text execute
.
A quick look at the seedu.address.logic.Logic
(an extract given below) confirms that this indeed might be what we’re looking for.
public interface Logic {
/**
* Executes the command and returns the result.
@@ -62,7 +65,7 @@
//We can deduce that the previous line of code modifies model in some way
// since it's being stored here.
storage.saveAddressBook(model.getAddressBook());
- } catch (IOException ioe) {
+ }} catch (IOException ioe) {
throw new CommandException(FILE_OPS_ERROR_MESSAGE + ioe, ioe);
}
@@ -209,7 +212,7 @@
Finally, you can step through until you reach the end ofMainWindow#executeCommand()
.
DG This is a good time to read through the UI component section of the DG
Here are some quick questions you can try to answer based on your execution path tracing. In some cases, you can do further tracing for the given commands to find exactly what happens.
[A] In this tutorial, we traced the "happy path" (i.e., no errors). What do you think will happen if we traced the following commands instead? What exceptions do you think will be thrown (if any), where will the exceptions be thrown and where will they be handled?
[B] What components will you have to modify to perform the following enhancements to the application?
ToC | What's next? Adding a Command
Authors:
GitHub Actions is CI/CD tool integrated into GitHub.
In the simplest case, setting up is a matter of adding a .yml
file into the [root]\.github\workflows
folder (example).
GitHub Actions will run the workflow (as per the .yml
file) every time certain project events are triggered (e.g., when a PR is updated, or the master
branch is updated).
GitHub Actions is CI/CD tool integrated into GitHub.
In the simplest case, setting up is a matter of adding a .yml
file into the [root]\.github\workflows
folder (example).
GitHub Actions will run the workflow (as per the .yml
file) every time certain project events are triggered (e.g., when a PR is updated, or the master
branch is updated).
Please refer to Intellij's own documentation here.
Note: step (b) is needed only if your project is using Gradle (i.e., if there is a build.gradle
file in the project root folder).
(a) Confirm the project JDK is set to the one you are supposed to use for the project, as explained here.
+(b) Confirm the correct JVM is used for Gradle, as given in the panel below:
If you are working with a forked repo that is using MarkBind already, refer to this guide instead.
MarkBind is a tool for generating static websites from markdown-like text, particularly suitable for text-heavy websites such as software project documentation.
Given below are some information useful for when you want to update documentation in a project that uses MarkBind.
MarkBind is a superset of Markdown. Refer the MarkBind user guide for more details.
First, start the live preview: Unless it is a trivial change, you would want to see how your change to the documentation source files will reflect in the generated website. You can use the MarkBind live preview mode to preview the generated website as you update the source file. To start the live preview mode,
[project root]/docs
-- if you are not sure, look for the folder containing the site.json
file).markbind serve
command. That will open the generated website in your default browser.Next, edit the files you want:
.md
files).While live preview can pick up most changes, it may not be able to pick up certain changes (e.g., changes to files in the _markbind
folder or changes to nunjucks macros). Furthermore, some syntax errors in your code can cause the live preview to crash. In those cases, just stop the server (Ctrl+C on Windows) and start it again.
Project admins can,
If you are working with a forked repo that is using MarkBind already, refer to this guide instead.
MarkBind is a tool for generating static websites from markdown-like text, particularly suitable for text-heavy websites such as software project documentation.
Given below are some information useful for when you want to update documentation in a project that uses MarkBind.
MarkBind is a superset of Markdown. Refer the MarkBind user guide for more details.
First, start the live preview: Unless it is a trivial change, you would want to see how your change to the documentation source files will reflect in the generated website. You can use the MarkBind live preview mode to preview the generated website as you update the source file. To start the live preview mode,
[project root]/docs
-- if you are not sure, look for the folder containing the site.json
file).markbind serve
command. That will open the generated website in your default browser.Next, edit the files you want:
.md
files).While live preview can pick up most changes, it may not be able to pick up certain changes (e.g., changes to files in the _markbind
folder or changes to nunjucks macros). Furthermore, some syntax errors in your code can cause the live preview to crash. In those cases, just stop the server (Ctrl+C on Windows) and start it again.
Project admins can,