Commenting code of a smart contact
Smart contract code - what are comments needed for
Smart contract is a self-executable code that is written in blockchain – a decentralized chain of blocks, has a broad purpose, one of which is automation of payment operations in the performance of contractual obligations.
When editing or finalizing smart contracts written by third-party programmers, you have to deal with the code without prompting, refer to additional documentation, if any. This process can be very long, time-consuming and unpleasant. Therefore, it is important to focus on commenting a smart contract code so that after some time you do not have to decompose it from the beginning.
Comments allow you to work with a specific block of code and not to search for answers throughout the code.
Rules of good style when commenting code, maintaining a single style of comments
- ability to separate explanatory and documentation comments;
- the comment should not duplicate the code, it should supplement it;
- all classes, fields, and methods must have documentation comments;
- when the meaning of variables accepted and returned by the method is not intuitive, documentation review must have a description of the content of those elements;
- if you use labels in break and continue statements, you must have a comment in the string;
- the comment must be in front of the documented item;
- comments should not contain spelling and punctuation errors;
- non-obvious fragments of code are allocated in separate functions, with detailed commenting on the purpose of their use.
- use the javadoc tool to create HTML-formatted documentation from source code comments in Java.
Benefits of correct code commenting
- save time spent by you, your colleagues, third-party developers to finalize, edit the code of the smart contract;
- absence of errors in the code or its misunderstanding due to incorrect or outdated comments;
- pleasant, comfortable work with the code and, as a result, its actual support and timely updating.