Published 15 October 2018

Комментирование кода смарт контракта

Код смарт контракта - для чего нужны комментарии

Код смарт контракта - для чего нужны комментарии

Смарт контракт – самоисполняемый программный код, который записывается в блокчейн – децентрализованную цепочку блоков, имеет широкое предназначение, одно из которых автоматизация платежных операций при выполнении контрактных обязательств.

При редактировании или доработке смарт-контрактов написанных сторонними программистами приходится разбираться с программным кодом без подсказок, обращаться к дополнительной документации,  если она есть. Этот процесс может оказаться очень долгим, трудоемким и неприятным. Поэтому следует сделать важный акцент на комментировании кода смарт-контракта, чтобы потом, через некоторое время не разбирать его с самого начала.

Комментарии позволяют работать с конкретным блоком кода и не искать ответы по всему коду.

Правила хорошего тона при комментировании программного кода, поддержание единого стиля комментариев

Правила хорошего тона при комментировании программного кода, поддержание единого стиля комментариев

  • умение разделять поясняющие и документационные комментарии;
  • комментарий не должен дублировать код, он дополняет его;
  • для всех классов, полей и методов должны быть документационные коментарии;
  • когда смысл принимаемыех или возвращаемыех методом переменных не понятен, документационный комментарий должен иметь описание содержания указанных элементов;
  • при использовании меток в операторах break и continue обязательно наличие комментария в строке;
  • комментарий должен находиться перед документированным элементом;
  • комментарии не должны содержать орфографических и пунктуационных ошибок;
  • неочевидные фрагменты кода, выделяются в отдельные функции, с подробным комментированием цели их использования.
  • используйте инструмент javadoc, для создания документации в HTML-формате из комментариев исходного кода на Java.

Преимущества корректного комментирования кода

Преимущества корректного комментирования кода

  • экономия времени затраченного вами, вашими коллегами, сторонними разработчиками на доработку, редактирования кода смарт-контракта;
  • отсутствие ошибок в коде или его непонимание ввиду некорректных или устаревших комментариев;
  • приятная, комфортная работа с кодом и как следствие его актуальная поддержка и своевременное обновление.
31 Useful article

Contents