Как начинающему программисту писать комментарии

Содержание:

Многие начинающие разработчики не умеют или, бывает такое, вовсе не хотят писать комментарии к коду. Новички считают, что код и так понятен без комментариев. Однако это далеко не так. Комментарии могут помочь программисту быстрее разобраться, в чем проблема, если приложение не работает и если за него уже отвечает другой человек, а не тот, который писал код.

Как начинающему программисту писать комментарии

Давайте посмотрим, чем помогут комментарии программисту

Так, комментарии в JS или комментарии в Питоне несут много полезного:

  • описывают сложные алгоритмы или функции. Они помогают не запутаться в математических, экономических расчетах при написании кода. Используя комментарии, в коде может разобраться тот, у кого нет знаний в математике или экономике;
  • дают понимание результата работы. Например, при отладке веб-приложения комментирование скелета HTML помогает протестировать быстрее те или иные кусочки кода;
  • не позволяют запутаться в логике. Так, комментарии в Python помогают создавать новые библиотеки, процедуры и функции, не прочитывая заново весь код. Программисты по комментам сразу находят место, куда необходимо вставить новую функцию.

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

Давайте посмотрим, как комментировать в HTML, Python и других языках.

Как комментируют опытные разработчики

В каждом языке, чтобы выделить комменты, программист использует различные символы. Вот только некоторые из них:

  • // — однострочные в языках C, C++, PHP, C#, Java и JavaScript;
  • # — однострочный в Python, PHP;
  • /* */ — многострочные в C, C++, PHP, C#, Java, JavaScript.

Есть определенные правила, которых должны придерживаться программисты, размещая свои комментарии. И вообще, начинающий программист должен избегать многих ошибок. Чтобы избежать их, нужно в совершенстве знать язык Java. О том, как легко выучить язык Java, узнайте в IT-блоге от DevEducation.

Какими правилами стоит руководствоваться

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

Вот некоторые из правил:

  • комменты следует размещать над кодом, к которому они относятся. Так проще будет понять, что к чему. Опять же не нужно расписывать на всю страницу, что происходит в коде. Достаточно сделать небольшие пометки в виде коротких предложений из пяти слов максимум;
  • рекомендуется делать комментарии на все основные детали кода. К ним относятся функции, классы, интерфейсы, методы;
  • писать коротко и только по делу. Опытные разработчики не рекомендуют писать: «Это красивый код», «Посмотрите на этот код!». Это все неверно. Просто указываете причину, по которой стоит коммент к коду. Желательно не использовать восклицательные знаки и просторечные выражения;
  • не рекомендуется писать оскорбительные слова в комментах или такие, которые не поймет технарь. Например, в Твиттере не используют сейчас следующие слова: blacklist, slave, master.

Комментарии классифицируются на два вида:

  • поясняющие;
  • документирующие.

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

Давайте посмотрим на один из комментариев, который дан ниже:

/**

Класс-коннектор для обеспечения взаимодействия с сервером

* Подключается через {@link Socket}

* посылает GET-запрос

* использует {@link ObjectInputStream} и {@link ObjectOutputStream}.

*/

public class ServerConnector

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

Как начинающему программисту писать комментарии

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

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

С помощью всего лишь одного символа можно автоматизировать создание комментов. Символ этот называется «собачка». И он всем вам знаком: «@».

Как происходит автоматизация:

  • @author — определяет автора исходника;
  • @param — задает характеристику метода;
  • @see — так выглядит комментирование ссылки;
  • @since — так определяют версию программного обеспечения;
  • @return — вид возвращаемых процедурой или функцией данных.

Это только часть автоматизирования комментариев. На самом деле способов много.

Давайте посмотрим, какие еще правильные и неправильные комментарии пишут новички:

int main()

{

double a,b;

// Принять от пользователя два числа

cin>>a;

cin>>b;

//Завести переменную для результата сложения

double sum = a+b;

// Вернуть результат сложения

cout<<sum;

return 0;

}

Вот так выглядит правильный комментарий.

/*

* Replaces with spaces

* the braces in cases

* where braces in places

* cause stasis.

**/

$str = str_replace(array(«{«,»}»),» «,$str);

А это тип плохого поясняющего комментария.

Заключение

При использовании комментариев, главное, знать, что они не спасут плохой код. Пусть теперь кодировка будет понятна для разработчика, однако плохое останется плохим. Поэтому не старайтесь комментариями «обелить» себя. Научиться правильно писать комментарии вы сможете на курсах программирования от обучающей компании DevEducation.

Присоединяйся к DevEducation — стань востребованным специалистом и построй карьеру в IT!