Многострочный комментарий javascript: Структура кода

Leave a Comment / Разное / By /

Содержание

Комментарии в Python — однострочные и многострочные

Содержание:развернуть

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

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

Комментарии — это еще один способ сделать ваш код более читабельным. Они могут помочь не только другим людям читать и понимать ваш код, но и вам самим. Бывают ситуации, когда вы быстро пишете какой-то код, не комментируя ни строчки.

Разработчики часто забывают, как работает их собственный код. Особенно если он был написан давно.

Комментарии — это отличный способ быстро вспомнить свой код, написанный ранее.

Хороший комментарии должны быть:

  • Уместными — не стоит указывать в комментариях очевидные вещи. К примеру, если вы назвали функцию print_black_list()
    , не нужно писать к ней комментарий # печать черного списка.
  • Содержательными — должны четко описывать проблему, не должно возникнуть никаких запинок по поводу их понимания.
  • Короткими — не нужно писать сочинение в комментариях.
  • Актуальными — одна из проблем комментариев это их сопровождение. Код меняется, а обновлять комментарии часто забывают. Чем старше ваш комментарий, тем больше вероятность, что он лжет.

Плохой комментарий описывает код, отвечая на вопрос «что делает код?». Хороший комментарий отвечает на вопрос «зачем этот код?».

О том, как правильно писать комментарии, отлично написано в книге Роберта Мартина «Чистый код», в главе 4 «Комментарии».

PEP 8 рекомендует использовать максимум 72 символа для комментариев на одной строке. Если ваш комментарий выходит за рамки 72 символов, его рекомендуется разделить на несколько строк.

О том, как создавать однострочные и многострочные комментарии в Python, разберем ниже.

Однострочные комментарии

Чтобы написать однострочный комментарий в Python, достаточно поставить «#» перед комментарием:

# Это однострочный комментарий print("python") # Это тоже однострочный комментарий

Python будет считать комментарием все, что находится после «#» и до конца строки.

Многострочные комментарии

Во многих языках программирования (например С++, Go, Java, JavaScript) можно создавать многострочные комментарии конструкцией вида /* */ В Python нет возможности создавать многострочные комментарии, и такая конструкция не сработает. Однако есть альтернативные решения.

Вариант #1 — писать однострочные комментарии друг за другом:

def multiline_comment_example(): # Это многострочный комментарий, оформленный # в виде однострочных комментариев, следующих # друг за другом

Вариант #2 — заключить комментарий в тройные кавычки:

""" Это многострочный комментарий, созданный с помощью тройных кавычек """

Второй вариант более удобен, но есть несколько нюансов, о которых нужно помнить.

  1. На самом деле это строка, которая не назначена какой-либо переменной. Эта строка не вызывается и ни на что не ссылается, поэтому может быть использована как многострочный комментарий.
  2. Если разместить такой комментарий сразу после определения функции или метода, Python будет считать его фрагментом документации, связанного с данной функцией/методом.

Многострочные комментарии, размещенные в определенных частях кода (например в самом начале модуля или сразу после объявления функции) могут служить документацией.

Шорткаты для комментариев

Процесс комментирования строк можно ускорить, используя шорткаты.

Несколько курсоров

Сразу несколько комментариев можно написать выбрав сразу несколько строк. Для разных редакторов они разные: Ctrl + Left mouse click или Alt + Left mouse click (Cmd + Left mouse click для Mac OS).

В редакторе можно писать комментарий сразу к нескольким строкам.

Свернуть комментарий

В некоторых редакторах (например PyCharm) можно свернуть комментарий, если он стал занимать слишком много места на экране.

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

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

Часто бывают ситуации, когда нужно закомментировать фрагмент кода (1 строку или сразу несколько строк подряд). Для этого просто выберите нужный фрагмент кода и нажмите Ctrl + / (Cmd + / для Mac OS)

Быстро закомментировать строки – Ctrl + / или Cmd + /

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

visual studio code — VScode закомментировать блок кода

Вопрос задан

11 месяцев назад

Изменён 6 месяцев назад

Просмотрен 637 раз

Как взять огромные куски кода в комментарии с помощью горячих клавиш?

  • visual-studio-code

2

Несколько способов, но сначала выделите блок, который будете комментить:

  1. По умолчанию на Windows Shift + Alt + A, для OS X Shift ⇧ + Option ⌥ + A.
    Поскольку я, например, использую Azure расширение, то данная комбинация переопределяется под него, поэтому данное сочетание клавиш может не работать. В этом случае можно назначить собственные горячие клавиши через интерфейс, который открывается при помощи
    Ctrl     + K Ctrl + S
  2. Через Command Palette
    F1 или Win:Ctrl + Shift + P или OS X:Shift ⇧ + Command ⌘ + P
    В строке ввести: Toggle Block Comment, выбрать и нажать Enter
  3. Через пользовательский интерфейс
    File -> Edit -> Toggle Block Comment

Результат будет отличаться для разных языков. Удобное использование заключается еще и в том, что при использовании данных горячих клавиш на закомментированых блоках, они будут раскомменчиваться.

Примеры

Python

""" import requests
for f in range(10):
    print(f) """

Javascript

/* let range = {
    start: new Date(),
    end: new Date(new Date().
  setDate(new Date().getDate() - 150)),
}; */

C

/* typedef enum
{
     INIT = 0
    ,DRAW
    ,PROCESSING
    ,EXIT
}eGameState; */

и тд

Это называется многострочный комментарий, в python это »’ в начале и конце нужного кода, к примеру:

'''print('assd')
   print('dasd')'''

5

Зарегистрируйтесь или войдите

Регистрация через Google

Регистрация через Facebook

Регистрация через почту

Отправить без регистрации

Почта

Необходима, но никому не показывается

Отправить без регистрации

Почта

Необходима, но никому не показывается

Нажимая на кнопку «Отправить ответ», вы соглашаетесь с нашими пользовательским соглашением, политикой конфиденциальности и политикой о куки

10 Рекомендации по комментированию JavaScript

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

В этой статье мы обсудим 10 лучших практик написания комментариев JavaScript. Мы рассмотрим такие темы, как когда комментировать, как форматировать комментарии и как сделать ваши комментарии полезными. Следуя этим рекомендациям, вы можете быть уверены, что ваши комментарии будут полезными, а ваш код будет легче читать и поддерживать.

1. Используйте // для однострочных комментариев

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

2. Помещайте однострочные комментарии на новую строку над темой комментария

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

3. Используйте /** … */ для многострочных комментариев

Многострочные комментарии используются для объяснения сложного кода или предоставления дополнительной информации об определенном разделе кода. Используя /** … */, вы можете легко отличить многострочные комментарии от однострочных (//). Это облегчает другим разработчикам чтение и понимание вашего кода.

Кроме того, некоторые IDE распознают синтаксис /** … */ и автоматически форматируют комментарий так, чтобы его было легко прочитать. Например, они могут добавить дополнительный интервал между строками или выделить определенные слова. Это помогает сделать ваш код более читабельным и понятным.

4. Размещайте многострочные комментарии на новой строке над темой комментария

Когда вы размещаете многострочный комментарий на той же строке, что и код, который он комментирует, его может быть трудно читать и понимать. Это также мешает другим разработчикам быстро просмотреть ваш код и найти то, что они ищут.

Помещая многострочные комментарии на новую строку над темой комментария, его становится намного легче читать и понимать. Это помогает другим разработчикам быстро определить назначение кода, не тратя время на расшифровку комментария.

5. Начинайте все многострочные комментарии со звездочки и пробела

Когда вы начинаете многострочный комментарий со звездочки и пробела, это облегчает чтение комментариев. Это также помогает поддерживать порядок и согласованность кода. Это особенно важно при работе над большими проектами с несколькими разработчиками.

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

6. Убедитесь, что каждая строка многострочного комментария начинается со звездочки

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

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

7. Заканчивайте все многострочные комментарии звездочкой и пробелом, за которым следует */

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

Завершая все многострочные комментарии звездочкой и пробелом, за которым следует */, вы гарантируете, что комментарий правильно закрыт и что никакой код не будет неверно истолкован как часть комментария.

8. Пишите подробные, содержательные комментарии

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

9. Не используйте комментарии для повторения того, что уже сказано в коде.

Комментарии следует использовать для объяснения того, почему код написан определенным образом, или для предоставления дополнительного контекста, который не очевиден при чтении кода. Если вы просто переформулируете то, что уже сказано в коде, то это будет излишним и внесет ненужный беспорядок.

Например, если в вашем коде написано «пусть х = 5», нет необходимости добавлять комментарий, говорящий «х установлено равным 5». Вместо этого используйте комментарии, чтобы объяснить, почему вы решили установить x равным 5, или любую другую соответствующую информацию, которая может помочь кому-то еще лучше понять код.

10. Избегайте написания очевидных комментариев

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

Комментарии в JavaScript — Учебник

по Джозеф Браунелл / Среда, 30 марта 2016 г. / Опубликовано в JavaScript, Latest

Комментарии в JavaScript: Обзор

            Комментарии в JavaScript в основном используются, чтобы объяснить, для чего предназначен код, или сделать его более читабельным. Однострочные комментарии начинаются с двойной косой черты (

// ), но не имеют закрывающего тега. Любой текст, написанный после ( // ), будет полностью проигнорирован JavaScript и не будет выполняться или отображаться браузером.

Стартовый «тег»:   //
Конечная «метка»: Нет
Пример:   // Запись в элемент с идентификатором «строка».

document.getElementById(«строка»).innerHTML=»Вы уверены?»;

Объяснение: Помечает код JavaScript, чтобы любой, кто просматривает, знал, что оператор должен записать в элемент с идентификатором «строка».

Комментарии в JavaScript — Учебник: картинка, описывающая использование однострочных комментариев в JavaScript.

            Многострочные комментарии в JavaScript начинаются с косой черты и звездочки (

/* ) и заканчиваются звездочкой и косой чертой ( */). Это позволяет разбивать ваши комментарии на несколько строк, делая их более читабельными для последующего редактирования. Как и однострочные комментарии, многострочные комментарии игнорируются JavaScript и не отображаются браузерами.

Стартовый «тег»:  /*
Конечная «метка»:   */
Пример: /*

Это

Пример

Многострочный комментарий.

*/

Объяснение: Позволяет писать комментарии в несколько строк, которые будут игнорироваться JavaScript и веб-браузерами.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *