Go to the main website [http://se-education.org/guides]
se-edu / guides Goto Github PK
View Code? Open in Web Editor NEWStyle guides and tutorials for SE student projects
License: MIT License
Style guides and tutorials for SE student projects
License: MIT License
Go to the main website [http://se-education.org/guides]
The current tutorial is a chain of many steps going up to 28 steps. It is told in the form of narration from start to finish.
It becomes challenging to link each step during tracing to the sequence diagram.
We can add headers to highlight which logic interaction is currently being traced, for example, when LogicManager
passes control to AddressBookParser
, we can explicitly mention this in header in whatever is the best form. It is hoped this can allow them to relate it to the introduced sequence diagram in high level overview in #16 easily
We can also highlight it in a diagram?
Add the tip mentioned in nus-cs2103-AY2223S1/forum#384 to the https://se-education.org/guides/tutorials/plantUml.html
Current:
Has 3 parts: echoing the user, adding dialog boxes, and adding custom behavior to dialog boxes.
Problem:
Lacking an introduction to even handlers in general. Students may lack a general understanding of event handlers, and may face difficulties when using event handlers for different controls.
Proposed:
Introduce the general logic for event handlers, some common event handlers for different controls, and a link to more advanced event handlers that are not likely to be used in the Duke project for exploration.
Current:
Problem:
Debugger features introduction
The use of the debugger features is relevant and crucial to the tutorial, but usage of these features are scattered with no explanation of what it means to show execution point, step into a method call, step over logging code or step out.
Include a section at the beginning to introduce features of the debugger and what they are used for.
Before diving into tracing code with IntelliJ IDEA’s debugger, it’s essential to understand key debugger features and their purpose. These features help you step through code systematically, inspect variable values, and understand program flow during execution. Here are the primary debugger features you'll use:
Purpose: Breakpoints pause program execution at specific lines of code.
Usage: Place breakpoints at critical points where you want to examine the program state, such as method entry points or before complex operations.
Purpose: Shows the current line of code where the debugger has paused execution.
Usage: Helps you navigate directly to the line where the program is halted, providing context for the next step.
Purpose: Steps into the implementation of a method called at the current execution point.
Usage: Useful for delving into how specific methods work, especially when you want to understand detailed functionality.
Purpose: Executes the current line of code without stepping into method calls.
Usage: Used to skip over lines of code that are not critical for understanding the current flow, such as logging or simple getter/setter methods.
Purpose: Executes the remaining lines of code in the current method and returns to the caller.
Usage: Useful when you've stepped into a method and want to quickly return to the higher-level context without stepping through every line.
Please have a look at the significantly-revamped Java FX tutorial here and report any problems or suggestions as separate issues in this issue tracker. If you found no issues, you can reply in this thread so that your effort doesn't go unnoticed.
Strongly suggested to follow the tutorial as if you are a student (i.e., actually do the steps given) so that we can tease out hidden issues.
As in the title. I suggest adding "don't hover the mouse over any link while saving as PDF" to https://se-education.org/guides/tutorials/savingPdf.html .
Reason: otherwise one of the link may look blackened and underlined like this.
I've added an empty VSCode guide at https://se-education.org/guides/tutorials/vscode.html
This page is supposed to provide helpful info for VSCode users, similar to what we have provided for Intellij.
However, VSCode is not supported officially by our courses, which means this guides will be an 'unofficial community resource'.
For the moment, let's keep it as one page, but we can split it into multiple pages later.
Feel free to send PRs to add content to this page, one section at a time. Perhaps best to post in this issue first to propose your content, to avoid PR overlap.
Inconsistency in the alert/tip boxes. This can make readers confused or feel that the content is very messy.
To standardise all tips (with the light bulbs) to be placed in the boxes. Certain tips can also be classified as “Note" or " Info" and be put in a different color box to avoid overwhelming the reader with too many tip boxes.
Note: This can be improved across all 3 tutorials.
Label and ImageView is created in handleUserInput and passed to DialogBox, which may increase dependency and reduce readability of code.
Constructor of DialogBox can be something as below:
public DialogBox (String s, Image i) {
text = new Label(s);
displayPicture = new ImageView(i);
// ...
}
handleUserInput can be something as below:
private void handleUserInput() {
String userText = userInput.getText();
String dukeText = getResponse(userInput.getText());
dialogContainer.getChildren().addAll(
new DialogBox(userText, user),
new DialogBox(dukeText, duke)
);
userInput.clear();
}
There is no common Debugging Tips/explanation section for new users
Instead of jumping around between web pages or sections, it would be helpful to have a consolidated debugging tips section filled with the most important information and tips for beginners.
For example: Beginners might not know the differences between step-in and step-over.
Add a basic tips section that serves as a quick summary and refresher for students not used to the debugger.
This section will include tips about the debugger's different functionalities and usages.
Problem:
Students might not know what to expect after setting a breakpoint at the first statement of the main method.
Proposed:
Insert the following paragraph at the end, to show the result of putting a breakpoint in the first statement of the main method:
Upon running the application with the breakpoint in the first statement of the main method, you will realize that the app is launched via this method.
Current:
"Styling" section only include those for containers and user input box. It also only gives instructions on styling to get the example UI, without much explanation.
Problem:
Styling for dialog box elements is not specifically mentioned. It is only mentioned later in part 3, but it is more relevant to part 2. Furthermore, this part does mention that readers should refer to the official JavaFX documentation for a comprehensive list of properties to modify. However, some students may not read them especially when they are given a ready-for-use piece of code for their individual project.
Proposed:
Also explore styling for Image View and text label.
Mentions some of the most commonly-used properties for each element as examples. For example, wrapping in text label and scroll panel and binding of width and height can be mentioned. Provide explanation for lines of code whose purposes are not immediately understandable.
Current:
ImageView and Label are shown as nodes in a VBox
Problem:
According to the mockup screenshot, the ImageView and Label are in a HBox which forms the DialogBox, and the DialogBoxes are stacked in a VBox as the content of the ScrollPane.
Proposed:
Under the "VBox" node, we should have:
HBox -> VBox
ImageView -> HBox
Label -> HBox
In Automating the testing of text UIs, the first sentence of Setting up is
Given below re steps to set it up for a project.
I believe "re" is a corruption of "are".
I ran a scan of all the pages under https://se-education.org/guides/ using Linkinator with the following command:
npx linkinator http://se-education.org/guides/ --recurse --format JSON
5 broken links were found below:
{
"Date Generated": "24/01/2023 20:12",
"URL List": [
{
"url": "https://mvnrepository.com/artifact/com.joestelmach/natty/0.6",
"status": 403,
"state": "BROKEN",
"parent": "http://se-education.org/guides/tutorials/gradle.html"
},
{
"url": "http://se-education.org/guides/conventions/index.page-vue-render.js",
"status": 404,
"state": "BROKEN",
"parent": "http://se-education.org/guides/conventions/java"
},
{
"url": "https://github.com/MarkBind/markbind/edit/master/.github/ISSUE_TEMPLATE/bug-report.md",
"status": 404,
"state": "BROKEN",
"parent": "http://se-education.org/guides/conventions/github.html"
},
{
"url": "https://mdn.beonex.com/en/CSS/Writing_Efficient_CSS.html",
"status": 404,
"state": "BROKEN",
"parent": "http://se-education.org/guides/conventions/css.html"
},
{
"url": "http://se.inf.ethz.ch/old/teaching/ss2007/251-0290-00/project/CSharpCodingStandards.pdf",
"status": 404,
"state": "BROKEN",
"parent": "http://se-education.org/guides/conventions/csharp.html"
}
]
}
The general steps to follow when solving this are as follows:
Tutorial primarily focuses on a single "happy path" scenario.
Users may not be familiar with how exceptions are thrown and handled, particularly CommandException
and ParseException
. This lack of understanding could lead to confusion, especially in subsequent tutorials that involve adding commands and handling these exceptions.
Enhance the tutorial by including examples of CommandException
and ParseException
being thrown and traced. This will help users understand the flow of these exceptions and how to manage them effectively in their code. This can be added before the Conclusion which also has other examples of possibly problem user inputs.
Currently most online tutorials use a coding pack to download the JDK, extensions.
However, CS2103T uses Java 11, hence the versions may cause an issue via the automated install. which may install Java 17.
We can break this down into
The page briefly introduces the remark
command format as remark INDEX r/REMARK
with a quick example.
For beginners or students who do not have a thorough understanding of the documents or architecture, the significance of INDEX and REMARK would not be immediately clear. They might not understand that INDEX refers to the position of the person in the address book list or how to format the REMARK text.
Enhance the explanation of the command format with a quick explanation. For instance, explain that INDEX refers to the list position of the person you want to add a remark to, and REMARK is the note or comment you wish to attach to their entry.
remark INDEX r/REMARK
E.g.: remark 2 r/Likes baseball
(adds the remark “Likes baseball” to the current person at index 2 of the observable list)
Current:
Problem:
Students might not understand what it means by “various event-driven mechanisms” and may be confused on the choice of placing the breakpoint where the UI transfer controls to the logic component.
Proposed:
Add a paragraph after the highlighted part:
This is because, unlike linear command-line programs, GUI applications respond to user actions (like clicks and keystrokes) and other events, triggering various event listeners and handlers. This non-linear flow of control can make it difficult to trace and debug the sequence of operations, as the program reacts dynamically to different events, creating an obscure execution path.
The tutorial introduces a architecture diagram and a high level sequence diagram. Afterwards it links to a developer guide.
Students may be overwhelmed by the information in developer guide and hence may not retain much. They may also forego reading it at all.
Instead of immediately directing students to the developer guide, start with a brief, guided overview of the essential component interactions. This overview will set the context for understanding the tracing code and make it easier for students to follow along.
Specifically,
Feedback appreciated thanks!
Fix these typos reported by past students, if still applicable
Typo in tutorial nus-cs2103-AY2324S2/forum#396
Typo in tutorial nus-cs2103-AY2324S2/forum#374
Typo in tutorial nus-cs2103-AY2324S2/forum#352
Typo in tutorial nus-cs2103-AY2324S2/forum#404
Typo in tutorial nus-cs2103-AY2324S2/forum#438
This section is relevant and can be helpful for students to check on their understanding. However, as no answers are provided it falls short of allowing students to check their knowledge fully as they cannot verify whether their answers and path tracing are correct.
Have a drop-down to reveal the answers for students to reference to, similar to the CS2103T website:
It is mentioned that tracing using a debugger would be useful in understanding an unfamiliar codebase, but not why or how it helps.
The current tutorial does not give the background context on why tracing execution paths is important, how it helps and an overview of the tutorial. This might leave beginners who do not know what a debugger is or those unfamiliar with the concept of code tracing to feel lost.
Add a detailed introduction that explains the importance of tracing code and what the reader can expect to learn.
## Introduction
Understanding the execution path of a program is crucial for debugging and extending existing codebases. Tracing code helps in identifying how different components interact, where potential bugs may occur, and how changes in one part of the code can affect the entire application. By the end of this tutorial, you will be equipped with the skills to:
* Set breakpoints effectively.
* Trace the flow of execution through various components.
* Understand the interactions between different parts of the application.
* Identify and troubleshoot issues within the code.
Given that this resource is shorter and also mostly done as a read-through, it might be helpful to have additional resources.
Once beginners complete the tutorial, they might be interested in learning more about refactoring techniques, IntelliJ IDEA, or other related topics to improve their skills. With additional suggested resources for further reading, we can provide them with a launchpad for them to further explore on their own.
Include a section on additional resources and further reading. Provide links to official IntelliJ IDEA documentation on refactoring tools, articles on refactoring best practices, and tutorials on advanced refactoring techniques.
It would be nice if there are intuitive directives to prompt the user to navigate to the next or previous page of a multi-page guide. For example, the JavaFX tutorial has 4 parts across 4 pages. Without the directives, some users might not be aware of other parts. Here is a sketch of what can be done:
On MacOS, preferences has been changed to settings. this is one instance in the guide where it appears wrongly @damithc should we update this for all the guides?
Create a brief guide to help users install the JDK, set up environment variables, and verify their installation across different operating systems.
Update the JavaFX guide to capture the tip given in nus-cs2103-AY2324S1/forum#111, if applicable
The tutorial states to check Use fx:root construct
but does not explain what it does.
Insert a link to the JavaFX-FXML documentation on what is fx:root and add the following:
Checking this enables the use of the fx:root
element, allowing you to reference a predefined root element. More about fx:root
on the documentation Introduction to FXML | JavaFX 2.2 (oracle.com).
The page can be structured similar to https://se-education.org/guides/tutorials/javaInstallationMac.html
While installation itself is rather easy, some students might not know how to configure their system to be able to run java
and javac
commands, how to switch between Java versions etc.
Note that this guide is used by students of different courses, some of whom could be first-time Java users.
The current version does not allow scrolling if the ScrollPane is unselected unless the scrollbar is clicked. Note that the code is referenced from part 4 of the guide.
Using ChatGPT, I find that this fix works by changing the way we automatically scroll to the bottom, but I do not fully understand why the initial version will cause the above issue.
MainWindow.java:
@FXML
public void initialize() {
//scrollPane.vvalueProperty().bind(dialogContainer.heightProperty());
dialogContainer.heightProperty().addListener((observable, oldValue, newValue) -> scrollPane.setVvalue(1.0));
}
Current:
Problem:
The code does not echo the tree diagram as there are no dialog boxes in the scroll pane. For the students to also learn about Vbox, Labels and Image View, instead of doing it later in this tutorial, this part of the code can include a sample dialog box.
Proposed:
Add in a temporary sample dialog box with image view and text label.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.