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

spec: Improve readability and quality of quint spec #671

Open
14 tasks
martin-hutle opened this issue Dec 12, 2024 · 1 comment
Open
14 tasks

spec: Improve readability and quality of quint spec #671

martin-hutle opened this issue Dec 12, 2024 · 1 comment
Labels
documentation Improvements or additions to documentation quint spec Related to specifications tech-debt Not high priority, to eventually be addressed.

Comments

@martin-hutle
Copy link
Contributor

The quint specification is sometimes inconsistent in naming and lacks documentation of the sometimes complex structure between the driver calls.
In particular the naming is inconsistent for

  • Votekeeper, vk, Bookkeeper bk
  • driverstate ds vs es
  • ns and state for NodeStates
  • val, p, address for consensus participants
  • DriverOutput vs toDriverResult

There is a name clash between

  • validators (val) as in valset and values
  • proposals and proposers
    Readability would profit from a consistent way to distinguish them .

Other issues are / improvements would be

  • replace consistently .with("") with (...x, )
  • split functionality for NodeState and DriverState in different files
  • ConsensusCall is never used
  • check if nextActionCommand is really needed. Maintaining two functions with same functionality can lead to inconsistencies
  • The handling of PendingDInput is a bit obscure:
    • in nextAction an input is chosen from pendingInputs and PendingDInput returned
    • driverLogic discards the selected input
    • handlePendingInput selects again from pendingInputs (and removes this then)
  • Consensus errors (ErrorOutput) are never used, tested or recorded
  • Adding helpful comments and function descriptions to the files (in particular for driver.qnt)
@martin-hutle martin-hutle added documentation Improvements or additions to documentation spec Related to specifications quint labels Dec 12, 2024
@cason
Copy link
Contributor

cason commented Jan 6, 2025

Can be seen as part of #468.

@cason cason added the tech-debt Not high priority, to eventually be addressed. label Jan 6, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation quint spec Related to specifications tech-debt Not high priority, to eventually be addressed.
Projects
None yet
Development

No branches or pull requests

2 participants