В последнее время на Хабре стало появляться довольно много статей о тех или иных аспектах программирования, которые позиционируются как статьи для «начинающих». Между тем, как раз для начинающих эти статьи часто являются непонятными: иногда — слишком сложными, иногда — не отвечающими на те вопросы, на которые должны, иногда — тяжелыми для восприятия.
Попробуем разобраться, как должна быть написана статья, если вы хотите, чтобы она не только понравилась, но и была полезна читателям.
Определите целевую аудиторию
Начните с определения вашей целевой аудитории. Понятие «начинающий» — весьма размыто. Вот несколько совершенно разных категория людей, которых можно назвать «начинающими»:
- Человек, который вообще никогда не слышал о программировании, и хочет научиться писать код.
- Человек, который знает некоторые теоретические основы (что делает компилятор, чем компиляция отличается от интерпритации, как вообще происходит процесс написания кода), но никогда не писал код сам
- Человек, который занимался программированием, но хочет перейти на несколько другой профиль (например, человек верстал простенькие сайты и знает javascript, но хочет научиться делать десктопные приложения)
- Наконец, человек, который достаточно неплохо знаком с программированием, но хочет изучить новый для себя язык или технологию.
Думаю очевидно, что статьи, ориентированнае на людей с разным уровнем, будут выглядеть совершенно по-разному. Тем не менее, большинство статей с пометкой «для начинающих» ориентированы на людей, которые с программированием знакомы поверхностно.
Определите начальные знания, необходимые для понимания Вашей статьи
Согласитесь, не так сложно написать в самом начале нечто вроде:
«Для понимания этой статьи читатель должен обладать начальными знаниями о C:
— уметь компилировать и запускать приложение
— знать синтаксис, основные типы данных и структуры управления»
Это не отнимает много времени, но очень сильно помогает читателям. Поверьте, если вы начинайте статью так:
Скомпилируйте следующий код:
int main(int argc, char *argv[]) { cout<<"Hello, world!"; }
то читатели могут вообще не понять, что от них требуется. Не забывайте, когда-то вы тоже не умели пользоваться компилятором.
Оформите статью как можно лучше
Хорошее и грамотное оформление — один из ключей к легкому пониманию материала.
Старайтесь писать весь код целиком
Я видел статьи и книги, в которых код приводился разрозненными кусками. Это приводит к тому, что читателю тяжело понять код, не говоря уж о том, что он не может этот код просто скопировать и запустить. Конечно, вы можете, например, писать разные функции в разных листингах. Это даже хорошо, так как облегчает понимание. Но не стоит разрывать на части логически однородный участок кода.
Не пишите так:
Пример программы, выводящей «Hello, World»:
//Начнем писать код int main(int argc, char *argv[]) { cout<<"Hello, world!";Какой-то (возможно, весьма полезный)
многострочный комментарий от автора//Продолжение return 0; }
Пишите так:
Пример программы, выводящей «Hello, World»:
#include <iostream> using namespace std; int main(int argc, char *argv[]) { cout<<"Hello, world!"; return 0; }Вот здесь можно писать длинный и развернутый комментарий, и даже еще раз написать ту строку
cout<<"Hello, world!";к которой он относится.
Если вам необходимо разбить код на несколько листингов, то было бы неплохо в конце статьи еще раз привести весь код в одном листинге, или даже дать ссылку, по которой этот код можно скачать.
Всегда проверяйте код, прежде чем вставить его в статью
Читателю меньше всего хочется сидеть и пытаться понять, почему пример из статьи не работает.
По этой же причине, если ваш код каким-то образом зависит от среды или компилятора, укажите это отдельно.
Всегда комментируйте код
Я миллион раз видел, как в книге встречается листинг на 3 страницы без единого комментария, а затем сплошным текстом идет описание того, что этот код делает. Такие вещи очень сложно читать. Попробуйте написать короткие комментарии в самом коде:
#include <iostream> //необходимо для использования cout using namespace std; //cout находится в пространстве имен std int main(int argc, char *argv[]) { cout<<"Hello, world!"; //вывод строки "hello, world" return 0; }
Не забывайте, что если для вас значение какой-то строки очевидно, то это не значит, что оно очевидно для всех. Если вы хотите подробно прокомментировать код, то неплохо будет вставлять номера строк. Не нужно нумеровать все строки подряд, достаточно сделать так:
1 #include <iostream> using namespace std; 4 int main(int argc, char *argv[]) { 6 cout<<"Hello, world!"; return 0; }В строке 1 мы подключаем заголовочный файл , который содержит классы, функции и переменные, необходимые для работы с потоковым вводом-выводом в C++. Мы подключаем этот файл для того, чтобы использовать объект cout, который представляет собой стандартный поток вывода.
В строке 4 начинается функция main — именно с этого места начнется работа нашей программы.
Наконец, в строке 6 мы выводим фразу «Hello, world» в стандартный поток вывода cout. Для этого применяется довольно простой синтаксис с использованием оператора <<. Слева от оператора записывается объект потока (в нашем случае cout), справа — выражение, которое должно быть выведено в этот поток.
Если вы хотите, чтобы читатель мог скопировать и запустить код, вы можете указать номера строк в комментариях, хотя это и менее наглядно:
#include <iostream> //(1) необходимо для использования cout using namespace std; //(2) cout находится в пространстве имен std int main(int argc, char *argv[]) { cout<<"Hello, world!"; //(6) вывод строки "hello, world" return 0; }
Поставьте себя на место читателя
Представьте, какие места в ваших примерах могут быть не очень понятны, и объясните их поподробнее. Если вам лень описывать какие-то вещи, которые легко найти в интернете или книгах, просто дайте ссылку на ресурс, где об этом можно почитать.
Постарайтесь не слишком усложнять код и избегайте перфекционизма
Не забывайте, вы пишите статью для новичка. Если вы можете сделать код проще, лучше это сделать. Если вы хотите показать, что код можно улучшить (пусть даже он усложнится), то напишите об этом после простого решения. Представьте, что вы объясняете человеку как работает оператор return, и для примера решили написать функцию, которая сравнивает два числа и возвращает наибольшее (или любое, если числа равны). Не стоит писать что-то вроде
template<class T> T compare(T a, T b) { return a>b?a:b; }
Напишите простой и понятный кусок кода:
int compare(int a, int b) { if(a>b) { return a; } else { return b; } }
Пусть его можно улучшить десять раз — это не важно, если ваша задача — показать суть метода, а не его конкретную реализацию.
Старайтесь придерживаться одного уровня во всей статье
Если вы начинайте писать статью на базовом уровне и подробно рассказываете о простых вещах, то делайте это до самого конца статьи. Если на середине статьи вы вдруг перестанете объяснять какие-то вещи, то читатель может совершенно потерять нить статьи и запутаться.
Придерживайтесь одного стиля во всей статье
Не важно, пишете ли вы в «академическом» стиле, или в стиле «а теперь, чувак, откомпилируем наше творение». Важно, чтобы вы были последовательны и не переключались с формального повествования на неформальное и обратно по десять раз за статью.
Старайтесь структурировать свои мысли
Вы рассказываете о программировании — а это значит, что ваше повествование, скорее всего, достаточно легко разделить на ключевые части. Старайтесь всегда делать это, потому что структурированную статью гораздо легче читать и понимать. Сплошная стена текста крайне сложна для восприятия, даже если сам текст рассказывает о достаточно простых вещах.
Старайтесь помочь читателю
Будьте вежливы в комментариях. Если вас попросят объяснить что-то подробнее, или добавить что-то в статью, постарайтесь это сделать (конечно, если у вас есть на это силы и время).
Заключение
Надеюсь, моя статья поможет авторам сделать свои статьи более понятными, а значит — и более популярными. Пожалуйста, пишите в комментах, если вы не согласны с какими-то пунктами, или хотите добавить что-то свое.
Автор: Singerofthefall
