Типичные улучшения

Для поиска по тегу начните название тега с символа '@'.

Улучшения, показаны 24 из 24.

Включите подсветку синтаксиса в блоках кода Markdown

Подсветка синтаксиса заметно облегчает чтение кода. Сразу становится видно где вызвана функция, где начинается цикл …

Вынесите вставки кода в отдельные блоки

В Markdown есть два формата для вставок кода. Первый — это inlines. Его применяют для …

Ответьте на дополнительные вопросы

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

Сделайте ссылки в документации кликабельными

Если ссылка в документе есть, но кликнуть по ней нельзя, то придется выделить и скопировать …

Разбейте одно предложение на несколько

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

Замените список на абзацы текста

В тексте и список, и абзацы решают одну задачу - задают структуру текста, разбивая его …

Избавьтесь от знаков препинания в заголовках

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

Перепроверьте утверждение

Некоторые из утверждений не верны.

Раскройте продуктовую ценность программы

В описании работы программы крайне нежелательно оперировать терминами "переменная", "функция", "цикл" и так далее. Ещё …

Замените термины с программистских на продуктовые

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

Расскажите о пользе на примере ситуации

Спросите любого в чём польза от того или иного приспособления, и собеседник сразу начнёт вспоминать …

Проиллюстрируйте то, о чём говорите

Некоторые вещи проще один раз показать, чем описывать словами. Сравните два описания: > Для работы …

Не используйте заголовки для выделения текста

Заголовки -- это особый элемент форматирования текста. Он предназначен для выделения главной мысли в абзаце, …

Включите подсветку синтаксиса

Код на питоне удобнее читать, если в нём есть подсветка синтаксиса. Сравните: +++ Без подсветки …

Используйте терминологию Python

В Python нет "массивов", вместо них используют "списки". То же самое со словарями: это теперь …

Используйте заголовки для разделения текста

Заголовки -- это особый элемент форматирования текста. Он предназначен для выделения главной мысли в абзаце, …

Включите подсветку синтаксиса в блоках кода Markdown

Подсветка синтаксиса заметно облегчает чтение кода. Сразу становится видно где вызвана функция, где начинается цикл …

Расскажите в README о переменных окружения

Программа берет настройки из нестандартных переменных окружения. Их не угадать без чтения кода.

Используйте в названиях правильный регистр букв

Верхний и нижний регистр букв в названиях имеют значение. По ним программист узнает тип сущности: …

Избегайте глаголов в названиях переменных

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

Используйте общепринятые сокращения

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

Избавьтесь от самописных примесей (mixins)

Mixins – это худшее, что может случиться с вашим кодом. Они подрывают стабильность кода, усложняют …

Разбейте одно предложение на несколько

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

deprecated