Skip to content
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

why obfuscated? #3

Closed
dtanner opened this issue Mar 13, 2019 · 5 comments · May be fixed by #4
Closed

why obfuscated? #3

dtanner opened this issue Mar 13, 2019 · 5 comments · May be fixed by #4
Assignees

Comments

@dtanner
Copy link

dtanner commented Mar 13, 2019

I wanted to inspect and validate one of the conversion functions, but noticed at least the java implementation is obfuscated. It's definitely unhelpful for me, and it seems odd to do this for an open source project. Maybe consider not doing that unless there's a good reason.

@Digidemic
Copy link
Owner

Hi Dan,
I understand your concern, however, this shortened naming structure was a conscience decision made shortly before UnitOf's initial release. This is something I knew would be asked at some point so I included it in the "Frequently Asked Questions" section at the bottom of the GitHub pages for UnitOf at the time of release.

In short, the reason for the shortened syntax is for file size, performance, and consistency across all languages.

To quote the question and answer from the FAQ:

LOOKING AT THE CODE, WHAT'S WITH THE NAMING OF CLASSES, METHODS, AND OTHER ELEMENTS AS RANDOM LETTERS?

Obsessing over compiled file sizes, performance, and consistent syntax amongst the 3 languages led to the shortened names in the code of UnitOf. During development, many experiments and tests were performed to see how slight changes in the naming conventions would affect the overall size of the final product. These changes to just a few letters resulted in better performance and smaller compiled size across all 3 languages. It was also important to try to have the syntax of all 3 languages as closely related as possible. Because JavaScript is an interpreted language, the amount of letters used here needed to be as few as possible. This ultimately affected the namings in the other languages as well. At the end of the day, we are proud to offer UnitOf in its entirety of 22 measurements for as little as 63.6kb.

So while this appears to be a bit of an annoyance at first, the overall end result of UnitOf is really what took priority.

In order to make the code easier to understand I made sure to include as much detailed documentation, comments, and examples in the code as possible. This making the code easier to understand, search, and navigate even if the syntax wasn't shortened.

For the most part, the structure of each measurement is consistent throughout the entirety of UnitOf. Other than "UnitOf.java", "A.java", and "B.java" each class is a single measurement of conversion factors. While the unit conversion factor keys are the abbreviations, each one is accompanied by a comment of what the full unit name is.

One way to find the proper super class of your desired measurement is to start with UnitOf.java > searching for your desired measurement finding the inner class declaration > observing the extended class being passed in as a generic type.
Example for Length: Searching for either "UnitOf.Length()", "class Length", or simply "length" in UnitOf.java > finding "public static class Length extends B ..." > Observing O.java contains all the Length units. The units here are all commented with their full names as well.

I hope that answered your question/concern and thank you for checking out UnitOf. If you have any other questions or even suggestions I would love to hear them.

Thank you
-Adam

@Digidemic Digidemic self-assigned this Mar 14, 2019
@dtanner
Copy link
Author

dtanner commented Mar 14, 2019

Hey thanks for the detailed reply Adam - I see where you're coming from and appreciate the detailed response. I only care about the java solution, in which I'd argue its optimization paths are very different than javscript (where download and interpretation speed really do matter), and I've never seen java source code obfuscated, but if it's works for you, then 👍 .
FWIW - The original reason I wanted to review the code was because it was a jar-only download and not available as a maven/jcenter distribution, so I wanted to verify it was clean code...the distribution of the jar is probably a more important issue for most people. Looks like that's issue #1.

@Digidemic
Copy link
Owner

Hey Dan,
I totally understand wanting to verify the solution. I began the steps needed to get UnitOf on Maven but got stuck about halfway through. In my opinion, the documentation for Maven is difficult to follow and their instructional multi-part videos are all listed as private. Regardless, they are not to blame for my inexperience uploading to maven, plenty of others have done so and continue to do so. I do wish the process was a bit easier though, uploading to npm and NuGet was simple and straightforward for example. Getting UnitOf on Maven is something I will try to prioritize soon.

Thank you for understanding!
-Adam

@sacot41
Copy link

sacot41 commented Jun 20, 2019

I'm not a javascript dev, so excuse me if I'm wrong, but, that's why minify tool exist. The source code of a library should never look like that. That's the job of the final dev to apply good minify tool on is code to optimise it.

@Zhuinden
Copy link

Zhuinden commented Jul 2, 2019

You could use Proguard (or potentially other minification tools) to apply minification at compilation time, you don't need to (and in fact: shouldn't) obfuscate the API of a library. 🙄

so I wanted to verify it was clean code...

Technically if your classes are named A, B, C, ..., Z and the comments hold the real name of your class's intentions, then it is NOT clean code.

However, I went through it and fixed that in an hour, so that's a plus.

Of course, I didn't modify any behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants