[refactor] Improve code structure #347 #348
Conversation
Refactored src/js/netjsongraph.js Fixes openwisp#347
dee077
force-pushed
the
issues/347-refactor-netjsongraph.js
branch
from
a239c8f to
fe99e6e
Compare
There was a problem hiding this comment.
Looks good @dee077! 👍
I have two minor requests for improvement regarding comments below.
src/js/netjsongraph.js
Outdated
| class NetJSONGraph { | ||
| /** | ||
| * @constructor | ||
| * Initializes a new NetJSONGraph instance. |
There was a problem hiding this comment.
Any programmer should know that a constructor initializes a new instance of the class, I think this comment can be removed.
There was a problem hiding this comment.
| * Initializes a new NetJSONGraph instance. |
Please remove this. Not useful.
There was a problem hiding this comment.
Please read https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/
I want to underline:
Rule 1: Comments should not duplicate the code.
The point is to explain what the comment achieves from a functional perspective or from the user perspective, eg: this code block implements the switching from geographic map to topology chart.
Rule 3: If you can't write a clear comment, there may be a problem with the code.
Rule 4: Comments should dispel confusion, not cause it.
Rule 5: Explain unidiomatic code in comments.
Rule 8: Add comments when fixing bugs.
Rule 9: Use comments to mark incomplete implementations.
And I would add: use comments when implementing workaround for issues, eg:
// This code works around a nasty bug in component X, TODO: solve the root cause,
// github issue link https://github.com/openwisp/.........
src/js/netjsongraph.js
Outdated
| class NetJSONGraph { | ||
| /** | ||
| * @constructor | ||
| * Initializes a new NetJSONGraph instance. |
There was a problem hiding this comment.
| * Initializes a new NetJSONGraph instance. |
Please remove this. Not useful.
Thanks for the clarification! I'll update the comments accordingly. |
| return { | ||
| ...config, | ||
| render: | ||
| config.render === "map" |
There was a problem hiding this comment.
@dee077 & @nemesifier
I found this in the readme
In extreme cases, you can also pass your own render function if you don't want Echarts to render. We will pass in the processed netjson data and netjsongraph object.
https://github.com/openwisp/netjsongraph.js?tab=readme-ov-file#configuration-instructions
I think, config can be undefined and user can pass custom render function so this need to be handled.
| * @param {Object} config - The user-defined configuration. | ||
| * @returns {Object} - The final configuration object. | ||
| */ | ||
| initializeConfig(config) { | ||
| initializeConfig(config = {}) { |
There was a problem hiding this comment.
I am not 100% sure if in Javascript this is an antipattern how in python is, but we have been bitten quite a few times by this issue in Python: https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments
Are you sure this is not goint to be problematic here? Are you sure this change is really necessary?
There was a problem hiding this comment.
I went through this doc
Evaluated at call time
The default argument is evaluated at call time. Unlike with Python (for example), a new object is created each time the function is called.
With this, I don't think there would be any problem.
src/js/netjsongraph.js
Outdated
| @@ -52,9 +49,6 @@ class NetJSONGraph { | |||
| }; | |||
| } | |||
|
|
|||
| /** | |||
| * Sets up rendering utilities, GUI, and event handling. Used in constructor | |||
| */ | |||
There was a problem hiding this comment.
I wouldn't remove this as it mentions quite a few interesting details which are good to know for someone who doesn't know the code.
src/js/netjsongraph.js
Outdated
| @@ -64,19 +58,15 @@ class NetJSONGraph { | |||
| } | |||
|
|
|||
| /** | |||
| * Initializes the ECharts rendering engine. Used in constructor | |||
| * Used in example Switch render mode | |||
There was a problem hiding this comment.
let's not mention the examples in the main code, the main code must not know about nor depend on the examples, it's the opposite: the examples depend on and know about the core netjsongraph.js code.
src/js/netjsongraph.js
Outdated
| this.echarts.clear(); | ||
| this.config.render = this.utils.mapRender; | ||
| this.utils.mapRender(this.data, this); | ||
|
|
||
| // Show Leaflet UI elements when back in map mode |
There was a problem hiding this comment.
I'd explain that we are showing again the credits and zoom control buttons when in map mode
There was a problem hiding this comment.
Added comment on both cases
src/js/netjsongraph.js
Outdated
| if (this.config.switchMode && this.type === "netjson") { | ||
| this.gui.renderModeSelector.onclick = () => { | ||
| // Switch from map to graph mode, first clear canvasContainer and then render |
Refactored
src/js/netjsongraph.jsFixes #347
Checklist
Reference to Existing Issue
Closes #347.
Description of Changes
Refactored
src/js/netjsongraph.js