-
Notifications
You must be signed in to change notification settings - Fork 427
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[#188] Adopt a uniform toString()
format
#189
Merged
damithc
merged 4 commits into
se-edu:master
from
Eclipse-Dominator:188-adopt-a-uniform-tostring-format
Jun 16, 2023
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
f9548da
Adopt a uniform toString() format for value classes
pyokagan 8a3152d
Messages: add format(Person) for formatting a Person for display
pyokagan a72be57
UniquePersonList: implement toString()
pyokagan 8c6b9f2
Prefix#toString(): annotate with `@Override`
pyokagan File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
53 changes: 53 additions & 0 deletions
53
src/main/java/seedu/address/commons/util/ToStringBuilder.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
package seedu.address.commons.util; | ||
|
||
/** | ||
* Builds a string representation of an object that is suitable as the return value of {@link Object#toString()}. | ||
*/ | ||
public class ToStringBuilder { | ||
private static final String OBJECT_PREFIX = "{"; | ||
private static final String OBJECT_SUFFIX = "}"; | ||
private static final String FIELD_SEPARATOR = ", "; | ||
private static final String FIELD_NAME_VALUE_SEPARATOR = "="; | ||
|
||
private final StringBuilder stringBuilder = new StringBuilder(); | ||
private boolean hasField; | ||
|
||
/** | ||
* Constructs a {@code ToStringBuilder} whose formatted output will be prefixed with {@code objectName}. | ||
*/ | ||
public ToStringBuilder(String objectName) { | ||
stringBuilder.append(objectName).append(OBJECT_PREFIX); | ||
} | ||
|
||
/** | ||
* Constructs a {@code ToStringBuilder} whose formatted output will be prefixed with the | ||
* canonical class name of {@code object}. | ||
*/ | ||
public ToStringBuilder(Object object) { | ||
this(object.getClass().getCanonicalName()); | ||
} | ||
|
||
/** | ||
* Adds a field name/value pair to the output string. | ||
* | ||
* @param fieldName The name of the field. | ||
* @param fieldValue The value of the field. | ||
* @return A reference to this {@code ToStringBuilder} object, allowing method calls to be chained. | ||
*/ | ||
public ToStringBuilder add(String fieldName, Object fieldValue) { | ||
if (hasField) { | ||
stringBuilder.append(FIELD_SEPARATOR); | ||
} | ||
stringBuilder.append(fieldName).append(FIELD_NAME_VALUE_SEPARATOR).append(fieldValue); | ||
hasField = true; | ||
return this; | ||
} | ||
|
||
/** | ||
* Returns the built formatted string representation. | ||
*/ | ||
@Override | ||
public String toString() { | ||
return stringBuilder.toString() + OBJECT_SUFFIX; | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Example Output: John Doe Phone: 12345678 Email: [email protected] Address: 123 Street Tags: [friend][classmate]
The Messages class serves as a utility class for formatting and storing user-visible messages. The class is utilized to create a user-friendly, readable string that represents a Person object. However, there are several aspects where this method could be improved:
Lack of Attribute Separators: The current formatting of the Person attributes doesn't include clear separators. This may lead to confusion when reading the output, particularly if a Person's name is erroneously interpreted as part of their phone number (for example, "John Doe Phone" might be misinterpreted as "John DoePhone"). Introducing distinct separators between attributes will greatly improve readability. A suggestion would be to include something like a colon (":") or a hyphen ("-") between the attributes.
Improving Code Cohesion: As it stands, the Messages class and ToStringBuilder class perform similar tasks, i.e., they both format objects into strings. To improve the code's cohesion, it might be beneficial to merge the Messages class's functionality into the ToStringBuilder class. This can help to keep all the string formatting logic in one place, making it easier for developers to find and use these APIs.
Enhancing Readability with ToStringBuilder: Since ToStringBuilder is already used in your codebase, it can be a good choice for implementing the format method, as it's designed for creating readable string representations of objects. The ToStringBuilder could be used to build the string with the added benefit of clear separation of fields, making the output easier to read.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I appreciate the suggestion, but I have plans in a future commit/pr to move the
Messages
class to withinlogic
package. As it currently stands, all functionalities ofMessages
class is related to displaying messages directly to the user via the GUI and it is right now exclusively used by thelogic
package. Thus, I feel that it is more appropriate to move theMessages
class directly into thelogic
package instead of keeping it incommons
package.The purpose of
ToStringBuilder
is mainly for devs to easily identify object string representations and their related data in logs and unit testings etc. Thus, it mainly serves as a way to enable easy debugging and testing. To enable this, user-facing messages will thus need to be migrated to use a different formatting method which was what was implemented here.I will definitely experiment adding additional purpose/functionalities to
toStringBuilder
based on your suggestion in 3!There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For 1, isn't the code already using
;
as the attribute separator?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The string output from the code when tested is as follows:
"John Doe Phone: 12345678 Email: [email protected] Address: 123 Street Tags: [friend][classmate]"
This output is used for user interface display. The separators between different elements (name, phone, email, address, tags) are crucial for readability and user understanding.
Consider the following examples:
"John Doe Phone" or "Address: 123 Street Tags: [friend][classmate]"
Without proper separators, the information can blend together and become confusing for the user. Therefore, I feel it's important to ensure that the separators are clearly defined and consistently used throughout the output.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
hmm...
toString()
is usually used for internal purposes (such as logging and debugging), to produce a compact string representation of the object. While it can be used for UI purposes, it might not be ideal as UI display have different considerations (easier reading, nicer formatting etc.). Is AB3 usingtoString()
method of Person class for UI display?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My apologies, I forgot to post a new iteration via CIHR sorry for the confusion, I have manually added the separator
;
in the format.Regarding adding multiple use case to the
toStringBuilder
, while it is possible I feel that the general use case for it might not as widely use. As mentioned beforetoStringBuilder
was originally meant as an easy way to print out object string representation while formatting is related to UI side details. So after some tweaking of code, I feel that there isn't enough usage to justify expandingtoStringBuilder
to allow customizing its display format.Perhaps it would be better to reconsider this when there are more use cases in the future which require similar formatting for user side message.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just realized that this method is specifically if for showring Person object details on the UI. So, the above doesn't apply.