Closed zepumph closed 1 year ago
Code review is complete. Overall the sim seems to be in good shape. The code is well structured and documented, and it's a very cool sim! Back to @Luisav1 and @zepumph for follow up on the issues that were logged during the review and the REVIEW comments that were placed in the code.
Alright! All review comments have been handled, and the remaining work here is covered by side issues. Thanks @jbphet so much for the thorough and speedy code review. Closing
PhET Code-Review Checklist (a.k.a "CRC")
// REVIEW
comments in the codeTable of Contents
Specific Instructions
Provide specific instructions here. For example: known problems that will fail CRC items, files that can be skipped, code that is not completed, shared or common code that also needs to be reviewed,... If there are no specific instructions, then delete this section.
GitHub Issues
The following standard GitHub issues should exist. If these issues are missing, or have not been completed, pause code review until the issues have been created and addressed by the responsible dev.
brands=phet
, see https://github.com/phetsims/build-a-nucleus/issues/119Build and Run Checks
If any of these items fail, pause code review.
ea
)fuzz&ea
)ea&listenerOrder=random
andea&listenerOrder=random&fuzz
)?deprecationWarnings
. Do not use deprecated methods in new code.Memory Leaks
grunt --minify.mangle=false
. Compare to testing results done by the responsible developer. Results can be found in {{GITHUB_ISSUE_LINK}}.dispose
function, or is it obvious why it isn't necessary, or is there documentation about whydispose
isn't called? An example of why no call todispose
is needed is if the component is used in aScreenView
that would never be removed from the scene graph. Note that it's also acceptable (and encouraged!) to describe what needs to be disposed in implementation-notes.md.Property.link
orlazyLink
is accompanied byunlink
.Multilink.multilink
is accompanied byunmultilink
.Multilink
is accompanied bydispose
.DerivedProperty
is accompanied bydispose
.Emitter.addListener
is accompanied byremoveListener
.ObservableArrayDef.element*Emitter.addListener
is accompanied byObservableArrayDef.element*Emitter.removeListener
Node.addInputListener
is accompanied byremoveInputListener
PhetioObject
is accompanied bydispose
.dispose
function should have one. This should expose a publicdispose
function that callsthis.dispose{{CLASS_NAME}}()
, wheredispose{{CLASS_NAME}}
is a private function declared in the constructor.{{CLASS_NAME}}
should exactly match the class name. Reviewer note: The only things disposed in this sim are particles and particle views, and these come from the 'shred' repo and already had dispose functions, so we're good to go.dispose
should either (a) useisDisposable: false
, or (b) implement adispose
method that callsDisposable.assertNotDisposable
. Use (a) for classes that inherit adispose
method from Disposable. Use (b) for classes that inherit adispose
method from something other than Disposable. The goal here is to prevent clients from callingdispose
for something that does not properly clean itself up, creating a memory leak. This is especially important for common code, but is good defensive programming for sim-specific code.~ Reviewer note: N/A since no new classes requiring dispose functions were added.Performance
webgl=false
) _Reviewer comment: Sim does not use WebGL, so we're good to go on this.Usability
showPointerAreas
)showPointerAreas
) Overlap may be OK in some cases, depending on the z-ordering (if the front-most object is supposed to occlude pointer areas) and whether objects can be moved.Internationalization
stringTest=dynamic
and use the left/right arrow keys.stringTest=X
. You should see nothing but 'X' strings.)stringTest=double
andstringTest=long
)stringTest=xss
? This test passes if sim does not redirect, OK if sim crashes or fails to fully start. Only test on one desktop platform. For PhET-iO sims, additionally test?stringTest=xss
in Studio to make sure i18n strings didn't leak to phetioDocumentation, see https://github.com/phetsims/phet-io/issues/1377StringUtils.fillIn
and a string pattern to ensure that strings are properly localized. This is relevant in cases where order should be translatable."{{value}} {{units}}"
) instead of numbered placeholders (e.g."{0} {1}"
).[x] Make sure the string keys are all perfect. They are difficult to change after 1.0.0 is published. They should be literal, they should be explicit, and they should be consistent. This will also be the PhET-iO phetioID name in Studio etc. Guidelines for string keys are:
(1) Strings keys should generally match their values. E.g.:
(2) If a string key would be exceptionally long, use a key name that is an abbreviated form of the string value, or that captures the purpose/essence of the value. E.g.:
(3) If string key names would collide, use your judgment to disambiguate. E.g.:
(4) String keys for screen names should have the general form
"screen.{{screenName}}"
. E.g.:(5) String patterns that contain placeholders (e.g.
"My name is {{first}} {{last}}"
) should use keys that are unlikely to conflict with strings that might be needed in the future. For example, for"{{price}}"
consider using key"pricePattern"
instead of"price"
, if you think there might be a future need for a"price"
string. (6) It is acceptable to prefix families of strings with a prefix, like so:Nested substructure is not yet fully supported.
Repository Structure
[x] The repository name should correspond to the sim title. For example, if the sim title is "Wave Interference", then the repository name should be "wave-interference".
[x] Are all required files and directories present? For a sim repository named “my-repo”, the general structure should look like this (where assets/, images/, mipmaps/ or sounds/ may be omitted if the sim doesn’t have those types of resource files).
*Any images used in model.md or implementation-notes.md should be added here. Images specific to aiding with documentation do not need their own license.
[x] Verify that the same image file is not present in both images/ and mipmaps/. If you need a mipmap, use it for all occurrences of the image.
[x] Is the js/ directory properly structured? All JavaScript source should be in the js/ directory. There should be a subdirectory for each screen (this also applies for single-screen sims, where the subdirectory matches the repo name). For a multi-screen sim, code shared by 2 or more screens should be in a js/common/ subdirectory. Model and view code should be in model/ and view/ subdirectories for each screen and common/. For example, for a sim with screens “Introduction” and “Lab”, the general directory structure should look like this:
[x] Do filenames use an appropriate prefix? Some filenames may be prefixed with the repository name, e.g.
MolarityConstants.js
in molarity. If the repository name is long, the developer may choose to abbreviate the repository name, e.g.EEConstants.js
in expression-exchange. If the abbreviation is already used by another repository, then the full name must be used. For example, if the "EE" abbreviation is already used by expression-exchange, then it should not be used in equality-explorer. Whichever convention is used, it should be used consistently within a repository - don't mix abbreviations and full names. The abbreviation should be all uppercase letters; e.g. MOTHAConstants, not MotHAConstants for "Model of the Hydrogen Atom".[ ] ⚠️ There is no asset file for fullNuclideChart.png, but it may not be possible to have one, see https://github.com/phetsims/build-a-nucleus/issues/180 Is there a file in assets/ for every resource file in sound/ and images/? Note that there is not necessarily a 1:1 correspondence between asset and resource files; for example, several related images may be in the same .ai file. Check license.json for possible documentation of why some resources might not have a corresponding asset file.
[ ] ❌ The README file needs to be updated, see #181 For simulations, was the README.md generated by
grunt published-README
orgrunt unpublished-README
? Common code repos can have custom README files.[x] Does package.json refer to any dependencies that are not used by the sim?
[x] Is the LICENSE file correct? (Generally GPL v3 for sims and MIT for common code, see this thread for additional information).
[x] Does .gitignore match the one in simula-rasa?
[x] In GitHub, verify that all non-release branches have an associated issue that describes their purpose.
[x] Are there any GitHub branches that are no longer needed and should be deleted?
[x] Sim-specific query parameters (if any) should be identified and documented in one .js file in js/common/ or js/ ( if there is no common/). The .js file should be named
{{PREFIX}}QueryParameters.js
, for example ArithmeticQueryParameters.js for the arithmetic repository, or FBQueryParameters.js for Function Builder (where theFB
prefix is used).[x] Query parameters that are public-facing should be identified using
public: true
in the schema.[x] All sims should use a color file named
MyRepoColors.ts
or, if using abbreviations,MRColors.ts
, and useProfileColorProperty
where appropriate, even if they have a single (default) profile (to support color editing and PhET-iO Studio). TheColorProfile
pattern was converted to*Colors.ts
files in https://github.com/phetsims/scenery-phet/issues/515. Please see GasPropertiesColors.ts for a good example.Coding Conventions
TypeScript Conventions
Math Libraries
DOT/Utils.toFixed
orDOT/Utils.toFixedNumber
should be used instead oftoFixed
. JavaScript'stoFixed
is notoriously buggy. Behavior differs depending on browser, because the spec doesn't specify whether to round or floor.IE11
string.includes
andstring.startsWith
where possible.Organization, Readability, and Maintainability
Pick
, but this is a bit of a hack. Here's an example:TODO
orFIXME
orREVIEW
comments in the code? They should be addressed or promoted to GitHub issues.{{REPO}}Constants.js
file?PhetColorScheme
. Identify any colors that might be worth adding toPhetColorScheme
.DerivedProperty
instead ofProperty
?Accessibility
This section may be omitted if the sim has not been instrumented with accessibility features. Accessibility includes various features, not all are always include. Ignore sections that do not apply.
General
Alternative Input
fuzzBoard&ea
)Node.pdomOrder
used appropriately to maintain visual and PDOM layout balance?