Giters

javascript-tutorial / ru.javascript.info

Современный учебник JavaScript

Home Page:https://learn.javascript.ru

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

[Предложение: учебник]: WeakRef & FinalizationRegistry

WOLFRIEND opened this issue · comments

commented

Описание

В JavaScript уже с 2020го года существует такой функционал как WeakRef и FinalizationRegistry, а в других языках программирование он присутствует намного дольше. На мой взгляд, было бы здорово сделать статью по теме этого функционала.

Мотивация

Вот небольшой список причин, почему по моему мнению нужно написать об этих возможностях:

  1. В учебнике уже присутствует материал на тему WeakMap и WeakSet, но ничего не сказано о WeakRef и FinalizationRegistry. Я считаю что читателям было бы полезно знать о всех существующих возможностях слабых ссылок.
  2. В списке issues уже существует запрос о написании материала на данную тему: javascript-tutorial/en.javascript.info#2831. То есть, есть спрос от пользователей.
  3. Это довольно редкая тема о которой многие разработчики даже не знают, не говоря уже об использовании. Было бы замечательно расширить общие знания, тем самым дав им стартовую точку для их собственных идей и реализаций. Как минимум, заложив базовые знания о существовании данных возможностей.
  4. Я, как автор данного issue, был бы рад помочь и взяться за написание данного материала. На самом деле информации об этом функционала и о том, как его использовать, не так много, но мне все равно есть о чем написать, есть опыт выступления конференции для разработчиков по данной теме и у меня есть демо-версия, показывающая, как это работает. Пускай материала будет и немного, но я думаю это будет отличной "отправной точкой" для познания этой темы.
  5. Я бы мог написать данный материал на трёх языках: Eng, Rus, Ukr.

Пожалуйста, дайте мне знать, как я могу внести свой вклад и сделать это?
На всякий случай вот мои контакты:
LinkedIn: https://www.linkedin.com/in/aleksandrtkaченко/
Электронная почта: wolfriend.official@gmail.com

Готовы ли вы принять участие в реализации данного предложения?

Да, я готов(а) принять участие.

commented

Добрый день.

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

  1. Нужно определить расположение данного материала: я больше склоняюсь к статье «Сборка мусора», там, скорее всего, информация о WeakRef и FinalizationRegistry будет более уместна.

    Ещё есть вариант с добавлением материала в статью «WeakMap и WeakSet». Если же информации по итогу получится слишком много, можем также вынести её в отдельную статью.

  2. Стиль написания текста.

    • Текст не должен быть слишком формального типа изложения. Посмотрите другие статьи на сайте, можете брать из них какие-либо определенные фразы и выражения, старайтесь придерживаться примерно такого же стиля.
    • Когда описываете какой-либо пример кода, используйте «мы», «нам», «у нас» и т.п. Например: «в коде выше мы воспользовались методом [...]»;
    • Когда советуете что-либо читателю: «Не используйте в этом примере метод [...]»; «Если вы пишете код в [...], используйте [...]»
    • Старайтесь избегать очень длинных предложений, разделяйте их по смыслу переносами строк:

    image

    • Обращение к читателю — на «вы», всегда с маленькой буквы (только если это не начало предложения).

    Подробнее здесь.

  3. Так как WeakRef и FinalizationRegistry — это очень узконаправленные возможности языка, приведите хотя бы по два примера из реальной жизни на каждый из них: в каких ситуациях они действительно полезны, где их будет сложно заменить чем-либо другим. У читателя не должно складываться впечатление, что это бесполезные структуры.

    Примеры должны быть свои. Мы не можем использовать в статье чужие готовые сниппеты, скажем, из MDN. Если вы нашли в интернете действительно какой-то очень хороший пример, отображающий суть работы этих структур, постарайтесь переделать его таким образом, чтобы он не был похож на свою первоначальную версию.

  4. Вся остальная необходимая информация для написания статей находится в Руководстве по редактированию учебника.

Если в процессе написания материала возникнут какие-либо дополнительные вопросы, что-то будет непонятно — всегда можете обратиться ко мне здесь, я постараюсь оперативно ответить. Текст будем ещё редактировать, чтобы привести в конечный вид, который можно будет опубликовать на сайте. Поэтому, если что-то не так сделаете, ничего страшного не произойдёт.

Как закончите работу — отправьте в этот репозиторий Pull Request (как это сделать, написано в руководстве, ссылку я привёл выше). После того, как примем правки в русской версии учебника — сможете перевести их и отправить в репозитории английской и украинской версий.

На этом этапе есть вопросы?

commented

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

commented

Здравствуйте.
Хочу сообщить вам, что я закончил своё написание статьи и уже сделал Pull Request:
#1899

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

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

  • Я создал отдельный раздел для этой темы, так как по моему мнению материала получилось вполне достаточно. Поэтому в изменениях Pull Request показывается большое количество изменённых файлов. Но большее их количество это всего лишь их перемещения (что б сохранить порядковые номера папок). По факту, всё что было добавлено мной, находится в папке: 1-js/05-data-types/09-weakref-finalizationregistry/.
  • Я видел инструкцию по переводу текста в картинках, но я так и не смог понять как именно вы создавали подобные картинки. Возможно вы использовали какие-то инструменты для этого. В моей статье также присутствуют некоторые диаграммы, для этого я использовал сервис https://app.diagrams.net/. Старался придерживаться тех же цветов что и в учебнике. Если необходимо, могу предоставить ссылку на исходный файл с диаграммами. Так как не совсем понятно как происходит механизм смены цвета при изменении темы оформления сайта.
  • После вашего рассмотрения, одобрения и утверждения финальной версии, готов приняться за дальнейший перевод на ENG и RUS.
commented

В течении следующей недели постараюсь рассмотреть ваш PR и прислать правки, если требуются. Спасибо.

commented

Здравствуйте.

Статья опубликована по ссылке https://learn.javascript.ru/weakref-finalizationregistry.

Сейчас я советую вам где-то в течении недели понаблюдать за секцией комментариев под статьёй: возможно, кто-либо заметит неточность, либо же будет где-то не совсем понятно. В таком случае, вы сможете отправить исправляющий Pull Request или попытаться объяснить более доходчиво, ответив на комментарии. Далее сможете перевести материал на другие языки и отправить по соответствующим репозиториям.

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

commented

Спасибо большое за вашу помощь.
Буду продолжать работать над переводом.