Останнім часом на Хабре стало з'являтися досить багато статей про ті чи інші аспекти програмування, які позиціонуються як статті для «початківців». Тим часом, як раз для початківців ці статті часто є незрозумілими: іноді - занадто складними, іноді - не відповідають на ті питання, на які повинні, іноді - важкими для сприйняття.
Визначте цільову аудиторію
Думаю очевидно, що статті, оріентірованнае на людей з різним рівнем, будуть виглядати зовсім по-різному. Тим не менше, більшість статей з позначкою «для початківців» орієнтовані на людей, які з програмуванням знайомі поверхово.
Визначте початкові знання, необхідні для розуміння Вашої статті
Погодьтеся, не так складно написати на самому початку щось на кшталт:
«Для розуміння цієї статті читач повинен володіти початковими знаннями про C:
- вміти компілювати і запускати додаток
- знати синтаксис, основні типи даних і структури управління »
Це не забирає багато часу, але дуже сильно допомагає читачам. Повірте, якщо ви починайте статтю так:
Скомпілюйте наступний код:
то читачі можуть взагалі не зрозуміти, що від них вимагається. Не забувайте, колись ви теж не вміли користуватися компілятором.
Оформіть статтю якнайкраще
Добре й грамотне оформлення - один з ключів до легкого розуміння матеріалу.
Намагайтеся писати весь код повністю
Я бачив статті та книги, в яких код наводився розрізненими шматками. Це призводить до того, що читачеві важко зрозуміти код, не кажучи вже про те, що він не може цей код просто скопіювати і запустити. Звичайно, ви можете, наприклад, писати різні функції в різних лістингах. Це навіть добре, тому що полегшує розуміння. Але не варто розривати на частини логічно однорідний ділянку коду.
Приклад програми, що виводить «Hello, World»:
Приклад програми, що виводить «Hello, World»:
до якої він відноситься.
Якщо вам необхідно розбити код на кілька лістингів, то було б непогано в кінці статті ще раз привести весь код в одному лістингу, або навіть дати посилання, по якій цей код можна скачати.
Завжди перевіряйте код, перш ніж вставити його в статтю
Читачеві найменше хочеться сидіти і намагатися зрозуміти, чому приклад зі статті не працює.
З цієї ж причини, якщо ваш код якимось чином залежить від середовища або компілятора, вкажіть це окремо.
У рядку 1 ми підключаємо заголовки. який містить класи, функції і змінні, необхідні для роботи з потоковим вводом-висновком в C ++. Ми підключаємо цей файл для того, щоб використовувати об'єкт cout, який представляє собою стандартний потік виведення.
У рядку 4 починається функція main - саме з цього місця почнеться робота нашої програми.
Нарешті, в рядку 6 ми виводимо фразу «Hello, world» в стандартний потік виведення cout. Для цього застосовується досить простий синтаксис з використанням оператора <<. Слева от оператора записывается объект потока (в нашем случае cout), справа — выражение, которое должно быть выведено в этот поток.
Поставте себе на місце читача
Уявіть, які місця в ваших прикладах можуть бути не дуже зрозумілі, і поясніть їх детальніше. Якщо вам ліньки описувати якісь речі, які легко знайти в інтернеті або книгах, просто дайте посилання на ресурс, де про це можна почитати.
Постарайтеся не надто ускладнювати код і уникайте перфекціонізму
Не забувайте, ви пишете статтю для новачка. Якщо ви можете зробити код простіше, краще це зробити. Якщо ви хочете показати, що код можна поліпшити (нехай навіть він ускладниться), то напишіть про це після простого рішення. Уявіть, що ви пояснюєте людині як працює оператор return, і для прикладу вирішили написати функцію, яка порівнює два числа і повертає найбільше (або будь-який, якщо числа рівні). Не варто писати щось на зразок
Напишіть простий і зрозумілий шматок коду:
Нехай його можна поліпшити десять разів - це не важливо, якщо ваше завдання - показати суть методу, а не його конкретну реалізацію.
Намагайтеся дотримуватися одного рівня в усій статті
Якщо ви починайте писати статтю на базовому рівні і детально розповідаєте про прості речі, то робіть це до самого кінця статті. Якщо на середині статті ви раптом перестанете пояснювати якісь речі, то читач може абсолютно втратити нитку статті і заплутатися.
Дотримуйтеся одного стилю у всій статті
Не важливо, пишете ви в «академічному» стилі, або в стилі «а тепер, чувак, откомпіліруем наше творіння». Важливо, щоб ви були послідовними і не переключалися з формального оповідання на неформальне і назад по десять разів за статтю.