Standardise conventions for comments and naming in Kernel

[phklive]

Feature description

Throughout the kernel different conventions for comments and naming have been used, e.g. in account.masm:

miden-base/miden-lib/asm/kernels/transaction/lib/account.masm

Lines 360 to 362 in 7ede403

	#! Panics:
	#! - slot index is out of bounds
	#! - computed index is out of bounds

miden-base/miden-lib/asm/kernels/transaction/lib/account.masm

Line 376 in 7ede403

#! Gets an item from the account storage. Panics if the index is out of bounds.

miden-base/miden-lib/asm/kernels/transaction/lib/account.masm

Lines 528 to 529 in 7ede403

	#! Panics if
	#! - index is out of bounds

miden-base/miden-lib/asm/kernels/transaction/lib/account.masm

Lines 421 to 423 in 7ede403

	#! Sets an item in the account storage. Panics if
	#! - the index is out of bounds
	#! - the slot type is not value

This is an isolated example with panics but it can be seen in documentation comments, naming of return values, etc...

Why is this feature needed?

We need to make sure that the code is clean, readable and understandable.

Furthermore setting the right conventions early will enable the project to scale easier.

[bobbinth]

Agreed!

In terms of naming, a few things that I noticed:

• get_output_notes_hash should probably be renamed into get_output_notes_commitment.
• We should probably use the same convention for all methods in the kernel. For example, we have set_account_item but `account_vault_add_asset. I think it should be either:
  • set_account_item and add_account_asset, or
  • account_set_item and account_add_asset.

[bobbinth]

@Fumuran - this is largely done already, right? Or is there something remaining?

[Fumuran]

The ABI PR mostly addressed the format of the comments and procedures, but I think there are still some ambiguity in naming, I'm not sure that we updated the usage of hash/commitment terms.

[bobbinth]

@Fumuran - could you create a more targeted issues for naming? Then we can close this one. Re hash vs. commitment - I think we should try to move away from hash toward commitment.

[Fumuran]

Created an issue: #1092