Как правильно писать комментарии к коду: несколько важных примеров

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

// TODO switch to the jest when it will works with modules import expect from 'expect'; import chalk from 'chalk'; 

solutionSlice:  // TODO move counter to server startTime: Date.now(), processState: isFinished ? solutionStates.shown : solutionStates.notAllowedToShown, waitingTime, >, 

# TODO Move to custom validator validates :first_name, length:  maximum: 40 >, format:  with: UsefulRegexp.without_spec_chars >, allow_blank: true 

Читайте также: Как читать чужой код: 6 правил, которые стоит помнить разработчику

#FIXME

Тег #FIXME показывает, что в этой части кода нужно что-то исправить. В некоторых случаях функциональность этого тега сливается с #TODO , поэтому #FIXME рекомендуется использовать, когда нужно указать на участок кода, от которого в будущем могут потенциально возникать проблемы.

# FIXME: Это нужно будет убрать, когда вернем аутентификацию для соцсетей user_from_session = get_session(conn, :current_user) 

// FIXME: это хак с путями, надо перерабатывать их root: path.join(process.env.HEXLET_IDE_APP_DIR, '..'), 

import/extensions: 0 # FIXME: remove when rule will be adjusted for new nodejs version 

#Warning

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

# Warning: The database defined as "test" will be erased and 

#Error

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

Как правильно применять теги

В каждой основной IDE есть плагины для работы с комментариями и их группировки. Например, в VS Code самый распространенный способ работы с такими комментариями — плагин Todo Tree , создающий дерево из групп комментариев для эффективной работы с ними.

В IDE от JetBrains комментарии #TODO и #FIXME автоматически определяются средой разработки в единые группы тегов. Подробнее об этом и том, как можно расширить функционал этой фичи на другие пользовательские комментарии, можно почитать на сайте JetBrains .

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

Как закомментировать CSS (и как писать комментарии)

Подпишись на наш телеграм-канал TechRocks WEB-разработка?

Комментарии — составляющая часть кода на любом языке программирования. Есть возможность комментирования и в CSS.

Если вы работаете в команде и занимаетесь большим проектом, вам нужна возможность как-то пояснять свой код товарищам. Тут вам на помощь придут комментарии.

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

В этой статье мы рассмотрим, как добавлять встроенные и многострочные комментарии в CSS.

Как закомментировать CSS

Чтобы закомментировать часть CSS-кода, вам понадобится обычный слэш ( / ) и астериск ( * ).

Для добавления как встроенного, так и многострочного комментария в CSS вы начинаете со слэша и астериска ( /* ). Их же, но в обратном порядке ( */ ) вы ставите в конце комментария.

Вот как выглядит встроенный (строчный) комментарий в CSS:

/* This is an inline comment in CSS */

А так выглядит многострочный комментарий:

/* This is a multi-line comment in CSS */

Вы также можете закомментировать те строки CSS, которые не должны выполняться:

/* .email-sub < padding: 0.2rem; border: 1px solid var(--primary-color); border-radius: 4px; >.email-sub:focus < border: 1px solid var(--secondary-color); outline: none; >*/

С помощью комментариев обозначают начало и конец стилей отдельных разделов на веб-странице:

/* Hero section starts */ .hero < display: flex; align-items: center; justify-content: space-between; gap: 1.9rem; max-width: 1100px; margin: 2rem auto -6rem; >/* Hero section ends */

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

/* Don't override this style if you don't know what you are doing. Otherwise, CSS might give you a kick in the butt */

Организация CSS при помощи комментариев

Примечание редакции Techrocks: этот раздел взят из другой статьи — «CSS Comment Example – How To Comment Out CSS».

В более крупных проектах CSS-файлы могут быстро разрастись. В результате их может стать трудно поддерживать. Упорядочивание СSS и разделение кода на отдельные части поможет лучше ориентироваться в стилях в будущем. При этом стоит также создать «Содержание» документа:

/* * CSS TABLE OF CONTENTS * * 1.0 - Reset * 2.0 - Fonts * 3.0 - Globals * 4.0 - Color Palette * 5.0 - Header * 6.0 - Body * 6.1 - Sliders * 6.2 - Imagery * 7.0 - Footer */ /*** 1.0 - Reset ***/ /*** 2.0 - Fonts ***/ /*** 3.0 - Globals ***/ /*** 4.0 - Color Palette ***/ /*** 5.0 - Header ***/ /*** 6.0 - Body ***/ h2 < font-size: 1.2em; font-family: "Ubuntu", serif; text-transform: uppercase; >/*** 5.1 - Sliders ***/ /*** 5.2 - Imagery ***/ /*** 7.0 - Footer ***/

Заключение

В долгосрочной перспективе комментарии в СSS могут помочь вспомнить, что вы делали, когда писали тот или иной код.

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

Строки комментариев (//) в CSS

CSS использует тот же синтаксис « блока комментариев », что и языки семейства C — вы начинаете комментарий с / * , и заканчиваете его * / .

Тем не менее, в CSS отсутствует правило синтаксиса « строка комментария », как в этих языках, где весь код от / / и до конца строки считается комментарием.

Многие разработчики просят, чтобы этот синтаксис также был добавлен, но, к сожалению, наши руки связаны — минимизаторы CSS не распознают строки комментариев.

Поэтому, если мы добавим такой символ, и минимизатор удалит все разрывы строк (как он, как правило, и делает), то строка комментариев выведет в комментарии все стили, следующие за ней!

Тем не менее, CSS на самом деле уже позволяет использовать символ / / . Но он используется не для всей строки, а для последующей конструкции.

То есть, когда вы используете / / , последующая конструкции CSS — будь то объявление или блок — будет « выведена в комментарии ».

В этом коде объявление height выведено в комментарии.

//@keyframes foo < from, to < width: 500px; >50% < width: 400px; >> @keyframes bar < from, to < height: 500px; >50% < height: 400px; >>

Здесь через / / выведено в комментарии первое объявление @keyframes .

Отмечу, что если вы попытаетесь использовать / / только для того, чтобы разместить в вашей таблице стилей комментарий, вам следует быть осторожными, — простой текст не является CSS конструкцией, так что при обработке таблицы стилей он будет пропущен, а в комментарии удалится первая следующая CSS-конструкция:

// Сделать какую-нибудь вещь. .foo < animation: bar 1s infinite; >/* Упс, блок .foo выпал в комментарии! */

Обновление: Упс, нашел ошибку у себя самого. К сожалению, синтаксис этого блока ( <> �� был некорректный.

Вы можете избежать этого, заканчивая текстовый комментарий символами <> (если вы не следуете правилам) или символом ; (если это объявление), чтобы дать CSS понять, что это просто шутка.

// Сделать что-нибудь <> .foo < animation: bar 1s infinite; >/* Теперь все правильно! */

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

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

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

Тем не менее, это все равно потенциально полезно для тех, кто не любит искать конец строки, чтобы закрыть комментарий символами * / , таких как я. ^ _ ^

Нужно добавить возможность оставлять комментарии к статьям [закрыт]

Вопросы с просьбами помочь с отладкой («почему этот код не работает?») должны включать желаемое поведение, конкретную проблему или ошибку и минимальный код для её воспроизведения прямо в вопросе. Вопросы без явного описания проблемы бесполезны для остальных посетителей. См. Как создать минимальный, самодостаточный и воспроизводимый пример.

Закрыт 4 года назад .

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

from RapterGames.news.forms import CommentsForm from .models import Articles class IndexView(generic.ListView): template_name = "news/posts.html" context_object_name = 'articles_list' def get_queryset(self ): return Articles.objects.all() def comment(request): form = CommentsForm(request.POST) comment = request.POST['comment'] context = if form.is_valid(): form.save() return redirect('registration/login.html') form = CommentsForm() context = return render(request, 'registration/registred.html', context) def aboutUs(request): return render(request,'news/aboutUs.html') 

from . import views from . models import Articles urlpatterns=[ path('', ListView.as_view(queryset=Articles.objects.all().order_by("-date")[:20],template_name="news/posts.html")), path('/', DetailView.as_view(model=Articles, template_name="news/post.html")), path('aboutUs', views.aboutUs, name='aboutUs') ]+ static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) 

from django import forms from django.forms import ModelForm, Form class CommentsForm(ModelForm): class Meta: model = Form fields = ('comenmt') 

from django.db import models from django import forms # Create your models here. class Articles(models.Model): title = models.CharField(max_length= 200) post = models.TextField() date = models.DateTimeField() img = models.ImageField(upload_to='', default="default_value") def __str__(self): return self.title 

  
 
>
 
 
 
<>
 
Опубликованно: >
 
 
 

Отслеживать
47.8k 17 17 золотых знаков 56 56 серебряных знаков 100 100 бронзовых знаков
задан 12 июн 2019 в 16:55
NeITdirect NeITdirect
23 1 1 серебряный знак 5 5 бронзовых знаков

1 ответ 1

Сортировка: Сброс на вариант по умолчанию

Основное отличие комментария (абстрактно) от других моделей в том, что мы не можем чётко определить его взаимосвязь с конкретной моделью, так как комментировать можно очень много всего.
Мы бы могли создать несколько моделей комментария на всё, что можно комментировать, но в Django есть более изящное решение.

Мы воспользуемся GenericRelation . Это позволит нам привязывать комментарий к любой из указанных моделей. Я для примера создам модель Post .

models.py:

from django.db import models from django.contrib.auth.models import User from django.contrib.contenttypes.models import ContentType from django.contrib.contenttypes.fields import GenericRelation from django.contrib.contenttypes.fields import GenericForeignKey class Comment(models.Model): author = models.ForeignKey(User, on_delete=models.CASCADE, related_name='comments') content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE) object_id = models.PositiveSmallIntegerField() content_object = GenericForeignKey('content_type', 'object_id') created = models.DateTimeField(auto_now_add=True) text = models.TextField(max_length=4096) class Post(models.Model): author = models.ForeignKey(User, on_delete=models.CASCADE) created = models.DateTimeField(auto_now_add=True) text = models.TextField(max_length=4096) comments = GenericRelation(Comment) 

Для того чтобы создать комментарий мы можем сделать следующее:

obj_type = ContentType.objects.get_for_model(post) Comment.objects.create(content_type=obj_type, object_id=post.id, author=user) 

Получить комментарии к конкретному посту можно так:

Comment.objects.filter(object_id=post.id) 

post — экземпляр модели Post .
user — экземпляр модели User (например, request.user в представлении).