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

Consider removing 1.3 of the purple paper for readability #28

Open
prestonvanloon opened this issue Apr 19, 2019 · 0 comments
Open

Consider removing 1.3 of the purple paper for readability #28

prestonvanloon opened this issue Apr 19, 2019 · 0 comments

Comments

@prestonvanloon
Copy link

prestonvanloon commented Apr 19, 2019

I'm not sure if there is a tracking issue for this already, but I would like to start a formal request not to use the language outlined in section 1.3 of the MakerDAO purple implementation paper.

Here are my arguments:

  • The code is unreadable without a memorized glossary or frequently referring to the written glossary.
  • Given this code is hard to read, it will be even harder to integrate with. This slows adoption of MCD in other contracts.
  • The benefit of using "concise names" have a one time benefit of reasoning about the system in a mathematical paper, but burden smart contract readers for the rest of time.

Addressing the motivations outlined in the purple paper:

We sidestep terminological debates; for example, whether to say »rate of target price change« or »target rate«.

This type of bikeshedding doesn't seem more of a concern than deciding whether or not to call something bump, hump, or sump.

With decoupled financial and technical vocabularies, we can more flexibly improve one without affecting the other.

That can still be done with proper variable names like liquidationPenalty rather than chop. In fact, this information is still present in the code so why not use it as the variable/property names?

The ability to discuss the system formally, with the financial interpretation partly suspended, has suggested insights that would have been harder to think of inside the normal language.

I can appreciate this, but perhaps a better solution is the inverse glossary where the formal discussion of properties can be translated into real words.

The precise and distinctive language makes the structure and logic of the implementation more apparent and easier to formalize.

I argue that this pattern makes the structure and logic less apparent. Again, it probably is easier to formalize, but harder to read from the code perspective. The formalization happens once while the code is read many times in the future.

Concise names make the code less verbose and the concepts easier to handle on paper, whiteboard, etc.

Less verbose isn't a good thing when you lose information/context in your code.

Please consider refactoring the code to be human readable.

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

No branches or pull requests

1 participant