Перевод статьи «How to Ask Good Technical Questions – the Ultimate Guide».
Умение задавать технические вопросы так, чтобы почаще получать хорошие ответы, — важный навык, которым должен обладать каждый разработчик.
Бывает, вы бьетесь над какой-то ошибкой и не можете понять, почему ваша программа работает некорректно. Или, скажем, никак не можете разобраться в реализации какого-нибудь алгоритма.
В этих и многих других ситуациях вы, скорее всего, выйдете в Интернет и разместите вопрос на Stack Overflow, в каком-нибудь сообществе на Discord, в сабреддите, в группе Facebook или даже просто напишете сообщение с этим вопросом другу.
Следуя советам из этой статьи, вы научитесь так задавать вопросы, чтобы они были легкими для чтения и понимания. Это облегчит задачу каким-нибудь добрым людям, изъявившим желание помочь вам с вашими проблемами.
Предоставьте контекст
Первое, на что нужно обратить внимание, — это контекст. Он помогает людям лучше понять ваш вопрос. Благодаря предоставленному контексту люди узнают о конкретной ситуации, в которой проявилась ваша проблема, а также о деталях, от которых может зависеть ответ.
Разработчики — не ясновидящие, они не всегда могут угадать, какой язык программирования вы используете или с какой платформой у вас проблемы. И настройки вашей среды они тоже вряд ли угадают, просто прочитав несколько примеров кода.
Если вы хотите получить качественный ответ на свой вопрос, все эти детали имеют значение. Между тем, многие разработчики упорно игнорируют необходимость предоставить контекст.
Скажем, вы используете C++ 1999 и пытаетесь применить функцию, доступную только в C++ 2011. Если вы не напишете об этих подробностях, люди могут начать искать проблему совсем в других местах.
Пишите информативные заголовки
Обобщите свой вопрос в заголовке. На Stack Overflow, например, у каждого вопроса должен быть заголовок, отражающий основную мысль. Название должно быть относительно кратким изложением сути вопроса.
Конечно, не все детали могут поместиться в заголовок. Но нужно постараться добавить их достаточно, чтобы при беглом просмотре заголовков люди смогли определиться, способны ли они помочь вам с этой проблемой.
Это важно, потому что у людей обычно нет времени, чтобы открывать и вычитывать каждый вопрос (особенно, если в подробном изложении они занимают несколько страниц). Сжатый, информативный заголовок, предоставляющий достаточно информации для принятия решения, позволяет экономить время.
Например, можно написать: «Сложение float и int с использованием оператора + расценивается в C++ 11 как int», а не «Операторы C++ не работают». Первый вариант дает достаточно контекста о вашей проблеме.
Создайте минимальный воспроизводимый пример
Если ваш вопрос связан с кодом, всегда включайте минимальный воспроизводимый пример. Это может быть полный репозиторий GitHub, гист или даже всего пара строк кода.
Не нужно копировать весь проект или весь репозиторий, с которым работаете. Добавляйте только те части, которые понадобятся людям, захотевшим вам помочь.
Если указываете репозиторий целиком, обязательно напишите, где именно искать. Четко укажите, какие файлы затронуты, какие функции в этих файлах нарушены и т. д.
Пример должен быть полным, т. е. достаточным для объяснения проблемы. В нем должны быть все необходимые импорты, внешние модули и функции. В нем должно быть все, что нужно, чтобы другие люди могли понять этот код и обдумать его.
При этом добавленный код должен быть минимальным и не содержать ненужных фрагментов. Показывайте только тот код, который напрямую связан с вашей проблемой.
Пример также должен быть воспроизводимым. Если я не смогу воспроизвести проблему, с которой вы столкнулись, то и помочь вам не смогу. Контекст и здесь играет важную роль. Отсутствие достаточного контекста и примеров затрудняет поиск ответа на ваш вопрос.
Расскажите о любых ограничениях
Обязательно упомяните о существующих ограничениях. Без этого люди будут давать дельные советы, но для вас они будут неприменимы из-за определенных рамок, о которых вы знаете, а советчики — нет.
Допустим, вы не можете решить учебную задачу, в которой вам не разрешается использовать сложные структуры данных. Если вы об этом не напишете, люди могут предлагать решения, включающие и сложные структуры. В результате и вы не быстро получите подходящий ответ, и люди зря потратят время. А это огорчает добровольных помощников, из-за чего они могут полностью проигнорировать ваш вопрос.
Также стоит учесть, что иногда мы совершенно напрасно сами себе ставим какие-то ограничения. Поэтому полезно подробно объяснить, почему эти ограничения вообще существуют. Люди могут вас удивить!
Избегайте использования скриншотов кода
Если вы приложите к своему вопросу скриншоты кода, скорее всего, эти изображения сожмутся на сайте. Их станет трудно читать, а если кода много, — и вовсе невозможно.
Изображение низкого качества не позволяет разработчикам копировать ваш код, чтобы попробовать его самостоятельно. Чтобы вам помочь, людям придется набирать ваш код вручную.
Это отнимает много времени и, вероятно, оттолкнет желающих помочь вам.
Также имейте в виду, что изображения не так доступны, как текст. Возможно, тема вашей IDE будет недостаточно контрастной для качественного скриншота, и людям будет трудно читать код. Имейте в виду, что ваш вопрос должен быть максимально доступным как можно большему числу людей.
Если вам необходимо добавить примеры кода, текст — лучший способ сделать это. Текст позволит программам чтения с экрана фактически прочитать ваш вопрос вместо того, чтобы говорить что-то общее, например «изображение». Это также позволит другим разработчикам читать код, не выходя из собственной темы браузера (подумайте о темных и светлых темах Stack Overflow).
Есть много способов поделиться кодом. Для этого существуют специальные решения, такие как Codepen, JSBin, GitHub Gist, Codesandbox и Pastebin.
Вы также можете просто вставить код в вопрос в виде текста. На платформах вроде Stack Overflow и форумов freeCodeCamp такая опция поддерживается (у кода даже будет подсветка синтаксиса). Но некоторые онлайн-сообщества требуют применения особых решений для размещения кода, и вы должны следовать этим требованиям.
Расскажите, что вы уже пробовали
Составьте список того, что вы уже испробовали. Это поможет вам не показаться лентяем, который ничего не сделал сам. К тому же, возможно, ваша последняя попытка была в крошечном шаге от успеха. Если вы не напишете, что уже пробовали, людям придется начинать с самого начала.
Советчики, вероятно, будут предлагать способы решения, которые вы уже испытали. Это будет расстраивать не только вас, но и их, ведь это пустая трата времени.
Образцы данных должны быть небольшими
Часто для тестирования кода, который мы пытаемся запустить, нам нужны образцы данных. Это может быть ответ объекта JSON с сотнями ключей от какого-то сервера или SQL- таблица с десятками или даже сотнями столбцов.
В этом случае следует ограничить объем информации, которую вы предоставляете в качестве выборочных данных. Зачем включать десять столбцов, если проблема связана только с одним из них? Со слишком большим количеством информации будет сложно работать.
Постарайтесь ограничить объем вашего кода. Предоставьте упрощенный объект JSON с ограниченным количеством ключей или таблицу SQL только с теми столбцами, которые касаются вашей проблемы. Это облегчит отладку, да и людям будет понятнее, с чего начать.
Код должен быть отформатированным и документированным
Никто не захочет читать код, сбитый в одну строку, с непоследовательными отступами, несогласованными именами переменных или плохим стилем в целом. По возможности придерживайтесь популярных соглашений.
Имена переменных и функций должны указывать на то, для чего они нужны. Люди хотят понимать, что делает функция, просто прочитав ее имя. Они не хотят расшифровывать код перед его прочтением.
Если дать описательные имена совершенно невозможно, убедитесь, что у вас есть хорошая документация. Задокументируйте, что делают функции, для чего предназначены переменные и как вы собираетесь их использовать.
Попробуйте также использовать линтер. Линтеры — это инструменты, которые проверяют ваш код и дают подсказки о возможных улучшениях логики, нарушениях стиля и соглашений, а также в целом помогают с читабельностью кода.
В общем, нужно, чтобы ваш код выглядел не так:
function someFunction ( p1,p2)
{
const b=p1+p2;
console.log(b+p1*p2);
if( b > some_Const) throw
Error ( "something went wrong")
else return 0;
}
а так:
function someFunction(p1, p2){
const b = p1 + p2;
console.log(b + p1 * p2);
if(b > SOME_CONST) throw Error("Something went wrong");
else return 0;
}
Это очень помогает при чтении кода и отладке. Форматировать свой код нужно вообще всегда, независимо от того, публикуете вы его в Интернете или работаете над ним в одиночку. Поверьте, это полезно.
Для форматирования кода есть много инструментов, но в веб-разработке наиболее популярны Prettier и ESLint. Они поддерживают несколько языков и работают с несколькими редакторами, такими как Atom, Vim, VSCode, Visual Studio и другими.
Почти все IDE поставляются со встроенным инструментом форматирования и линтером. Поэтому, прежде чем обращаться к сторонним инструментам, присмотритесь к своей IDE.
Проверьте правописание
Иногда вопросы сложно расшифровать из-за слишком большого количества грамматических ошибок. Это затрудняет чтение и ограничивает количество людей, желающих вам помочь.
Такие платформы, как Stack Overflow, дают редакторам возможность улучшать вопросы, но вы не должны полагаться на это. На других платформах нет такой поддержки, поэтому обычно рекомендуется проверять грамматику ваших вопросов до и после их публикации.
Инструменты вроде Grammarly автоматически сканируют ваш текст и дают советы по улучшению грамматики или даже исправляют чисто грамматические ошибки. У Grammarly есть расширения для Firefox, Chrome, Safari и Edge. Попробуйте.
Отслеживайте судьбу своего вопроса
Одна из самых неприятных вещей для людей, отвечающих на вопросы в Интернете, — это отсутствие обратной связи.
Если вы задали вопрос и получили ответ, не улетучивайтесь моментально. Дайте людям, пытавшимся вам помочь, обратную связь. Расскажите им, что сработало, что не сработало и почему.
Часто вы можете остаться с частичным решением, но без обратной связи вы никогда не доберетесь до полного.
Иногда вас попросят предоставить дополнительную информацию. Возможно, вы забыли некоторые из наших советов или не предоставили достаточно подробностей. Приветствуйте фидбэк с улыбкой и отвечайте.
И помните: людям не платят за эти услуги. Они жертвуют своим временем и усилиями, чтобы помочь вам, поэтому цените это и работайте с ними, чтобы предоставить им как можно больше информации. В конце концов, это окупится.
Добавьте резюме
В целом, старайтесь, чтобы ваши вопросы были короткими. Чтение длинных вопросов занимает много времени, и из-за этого их часто игнорируют. Я не буду читать три страницы вопроса, заранее не зная, смогу ли вообще чем-то помочь.
Если ваш вопрос очень длинный, то помимо информативного заголовка добавьте еще и резюме в начале текста. Краткая версия вопроса даст людям возможность определиться, стоит ли читать вопрос целиком, смогут ли они помочь.
Все мы люди
Полученные ответы не всегда будут благожелательными и приветливыми. У людей есть своя жизнь, полная проблем. Если вы будете слишком давить на собеседников, они могут начать игнорировать вас или вообще удалят свои ответы. Уважайте частную жизнь людей и не загоняйте их в угол.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
