Published 15 October 2018

Commenting code of a smart contact

Smart contract code - what are comments needed for

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

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

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.
0 Useful article

Contents