Explore refactoring code base's formatting to improve readability

aisingapore / TagUI

Free RPA tool by AI Singapore

Apache License 2.0

5.67k stars 584 forks source link

Explore refactoring code base's formatting to improve readability #490

Closed kensoh closed 5 years ago

kensoh commented 5 years ago

Most of TagUI's code was written while I was on a year plus sabbatical, mostly in Eastern Europe. There is no external monitor, so on my Vim editor, I pack lines of code tightly to maximise screen real estate. This helps to reduce development time.

Though the project is unlikely to often have contributions and PRs from users, improving the formatting would make it easier for someone else to maintain the codebase at AI Singapore in future. Raising an issue to look into that.

Python code is already formatted due to its inherent indentation formatting. Some of the newer code are already formatted nicely. The bulk of the code re-formatting would likely be in tagui_parse.php and tagui_header.js.

For post-change, besides testing the translation test cases in positive_test, there is a need to validate further to ensure no regression in functionality.

kensoh commented 5 years ago

List of TagUI source files with easy-to-read formatting - 43/46 (93% of files)

[x] 8 source files in chrome folder
[x] 1 file in languages folder
[x] 0 file in media folder
[x] 14 files in samples folder
[x] 1 file in tagui.sikuli
[x] 1 file in tagui_py
[x] 1 file in tagui_r
[x] 1 file in test
[x] end_processes
[x] end_processes.cmd
[x] erina
[x] erina.cmd
[x] sleep.php
[x] transpose.php
[x] tagui
[x] tagui.cmd
[x] tagui_chrome.php
[x] tagui_config.txt
[x] tagui_crontab
[x] tagui_footer.js
[x] tagui_helper.php
[x] tagui_report.php
[x] tagui_runner.php
[x] tagui_service.php

List of TagUI source files with hard-to-read formatting - 3/46 (7% of files)

[x] tagui_header.js
[x] tagui_parse.php
[x] translate.php

kensoh commented 5 years ago

More details at issue #490. Only 7% of files are not formatted for easy reading. It makes no sense to refactor these 7% (3 files tagui_header.js, tagui_parse.php, translate.php) at a risk of hurting existing compatibility and scripts. Solution is to provide beautified snapshots of these 3 files and add link to these snapshots at top of the files, so that any developer who wishes to view or edit the source code can see the beautified version.

As TagUI is an engine that tries to translate human languages into working JavaScript code that works with its various components, it has mash-up code using string manipulations and replacements in order to get some things done. Simply using a beautifier may break some parts of the engine that affects some existing users' scripts. Thus it is better to provide beautified versions for the 7% of files that is hard to read, than try to refactor at risk of breaking existing users' scripts.

kensoh commented 5 years ago

Committed to master, closing issue.

kensoh commented 4 years ago

Dummy checklist to go through codebase on functional level with @siowyisheng -

[x] TagUI architecture
[x] tagui.sikuli/tagui.py
[x] tagui_py/tagui_py.py
[x] tagui_r/tagui_r.R
[x] test/positive_test
[x] end_processes
[x] end_processes.cmd
[x] erina
[x] erina.cmd
[x] sleep.php
[x] transpose.php
[x] tagui_chrome.php
[x] tagui
[x] tagui.cmd
[x] tagui_config.txt
[x] tagui_crontab
[x] tagui_footer.js
[x] tagui_helper.php
[x] tagui_report.php
[x] tagui_runner.php
[x] tagui_service.php
[x] tagui_parse.php
[ ] tagui_header.js
[ ] translate.php
[x] chrome extension