Авторите на книгите от поредицата "Programming Basics" (Основи на програмирането) се съгласяват да следват настоящите насоки, за да се уеднакви стилът на писане.

Целта на книгите е да се ползват като учебник за курсовете "Programming Basics" в СофтУни.

• Следваме слайдовете от курса "Programming Basics" в СофтУни: https://github.com/SoftUni/Programming-Basics-Resources/tree/master/CPlusPlus-Course-SoftUni).

• Можем да добавяме и допълнителна информация, не сме 100% вързани за слайдовете.

• Ползваме GitBook платформата, защото тя е много подходяща за open-source книги: https://cpp-book.softuni.bg.

• Лицензът е CC-BY-SA.

Стараем се да форматираме кода качествено, да слагаме заглавията в добра йерархия (H1, H2, H3) и да слагаме bold за ключови фрази от всеки абзац, за да улесним четенето на текста и навигирането в него с поглед.

Ползваме Markdown форматиране в GitBook платформата. Където не става с Markdown, слагаме HTML (примерно за входа и изхода в условията на някои задачите).

Всички елементи от кода (имена на променливи, keywords, имена на файлове и подобни) форматираме като код ограден ляв апостроф. Пример:

В C++ можем да повтаряме команди с for цикъл. Операторът for повтаря група команди няколко пъти.

C++ кодът се форматира по стандартния за markdown езика начин, като езикът е "cpp". Пример:

   for (int a = 1; a <= 100; a = a + 1) {
      cout << a << endl;
   }

Често пъти при подсказките към задачите искаме да дадем screenshot с кода вместо самия код, за да избегнем възможността за copy / paste. В тези случаи трябва да се взима screenshot от Visual Studio (със светла тема), за да е оцветен правилно кода. Ето добър пример:

Понякога нарочно замъгляваме част от кода, за да накараме читателят да мисли, вместо да преписва на сляпо кода:

Примерните вход и изход при задачите за упражнения се форматират като в примера по-долу с използване на HTML тагове и по-конкретно <br> за слизане на нов ред. Ето пример:

• Правим картинките като PNG и се стараем да са с добър контраст.
• Размерът (width) да НЕ Е по-голям от 640px.
• Да не се ползва JPG, защото чупи качеството на изображението.
• Резолюцията (DPI) трябва винаги да е 96:

• При картинки с код - големината на шрифта трябва да е като този на картинката по-долу (не е използван zoom, но при различните устройства може да е друго).
• Темата на Visual Studio e светлата. ("Light")
• Размера на шрифта в VS е 10, Consolas, zoom 100% (при различните устройства може да е различно). Вижте как да промените настройките в записки от учредителната среща.
• Картинките се организират в папка assets, като всяка глава си има своя папка. Обръщаме внимание на именуването на картинките - нека в заглавието присъства информация за номера и името на задачата или примера, за които е използвана картинката, както и поредността й. Пример за добро именуване на файл: 13.Fibonacci-01.png.

Пример:

Когато взимаме картинки от слайдовете, се стараем да ползваме цветовете от PPTX шаблона за картинки. Трябва да се получи нещо такова:

Пишем в множествено число. Пример:

Да разгледаме кода на примерната програма. На първия ред забелязваме .... Тя служи за ...

Заглавията следват структурата на слайдовете. Слагайте повече подзаглавия, за да е по-хубаво структуриран текстът.

• Heading 1 - заглавие на глава от книгата
• Heading 2 - заглавие на секция от дадена глава
• Heading 3 - заглавие на под-секция от дадена глава
• ...

Важни забележки, на които искаме да обърнем специално внимание, се правят със следния HTML код:

<table><tr><td><img src="/assets/alert-icon.png" style="max-width:50px" /></td>
<td>Тази книга ви дава само <b>първите стъпки към програмирането</b>. Тя обхваща
съвсем начални умения, които предстои да развивате години наред докато достигнете
до ниво, достатъчно за започване на работа като програмист.</td>
</tr></table>

Резултатът е нещо такова:

Не променяйте HTML кода. Той е внимателно написан, за да се визуализира коректно на лаптоп, таблет, телефон и като PDF).

Можем да вмъкваме YouTube видео клипчета в книгата със следния HTML код:

<div class="video-player">
  Гледайте видео-урок по тази глава тук: <a target="_blank"
  href="https://www.youtube.com/watch?v=LgT10WCBw0M">
  https://www.youtube.com/watch?v=LgT10WCBw0M</a>.
</div>
<script src="/assets/js/video.js"></script>

Горният код ползва малко JavaScript, който се изпълнява в GitBook при рендиране на книгата в HTML формат. В GitHub не се изпълнява, както и при PDF рендиране. Така в PDF се показва текст в стил "гледайте видео тука + link", а при HTML формат на книгата, се появява YouTube video player с page width (responsive) размери (width: 100%, height: изчислява се по формат 16/9). При преглеждане на страницата с GitHub markdown viewer, се появява линк към видеото.

За примерните задачи и задачите за упражнение, в заглавията да се ползва Heading 3 и винаги да се изписва по следния начин:

• Задача: <наименование> или
• Пример: <наименование>

Пример:

###Задача: числата от N до 1 в обратен ред

###Пример: числата от N до 1 в обратен ред

Тествайте решението си тук: https://judge.softuni.bg/Contests/Practice/Index/514#11

Тествайте решението си тук: https://judge.softuni.bg/Contests/Practice/Index/514#11

Форматирането на ключови фрази, понятия, думи в текста се правят bold. Това подобрява четимостта на текста.

Пример:

Сега ще напишем логиката по пресмятане на броя тухли на ред, която ще използваме след това, за да изчертаем тухлите. -> Сега ще напишем логиката по пресмятане на броя тухли на ред, която ще използваме след това, за да изчертаем тухлите.

**пресмятане на броя тухли на ред**

Където предстои промяна, слагайте маркер [TODO], примерно [TODO: update judge link]. Ще ползваме TODO маркер за моменти, които не можем да поправим на момента или са обект на дискусия. Засега просто ги отбелязвайте.

Пример:

[TODO: update judge link]

Ако използваме TODO маркер в някой от скрийншотите, коректният начин на изписване е следния: // TODO: ...

За всички теми: да се тества какво става на таблет / телефон и да се измисли как да се адаптира съдържанието. Най-честият източник на проблеми за responsive design са таблиците. Избягвайте много колони в таблиците. Повечето могат да се направят на няколко отделни таблици с по-малко колони. Знам, че в оригиналните MS Wоrd файлове ползваме много колони, за да спестим място. Обаче тази книга трябва да е четима от телефон и по-добре да помислим за това. След тестване установихме, че е по-добре да се ползва markdown

Пример:

| Вход | Изход | Вход | Изход | Вход | Изход |
| :--- | :--- | :--- | :--- | :--- | :--- |
| 2<br>10<br>20 | 30 | 3<br>-10<br>-20<br>-30 | -60 | 4<br>45<br>-20<br>7<br>11<br> | 43 |

Когато имаме име на функция в текста, ползваме () или (…), за да улесним читателя. Примерно trunc -> trunc(…). Първото изглежда като property. Второто е очевидно, че е функция / метод, защото има някакви параметри в скобите.

Пример:

trunc(10.25);

След предлог в българския език винаги следва кратък член. Грешно:

"на последният ред".

Вярно:

"на последния ред".

Пълен член се слага, ако фразата отговоря на въпроса "кой"? Пример

"операторът == сравнява две стойности".

Въпрос: кой? Отговор: "операторът ==".

Кратък член се слага, ако фразата отговаря на въпроса "кого?". Пример:

"чертане на първия стълб" -> "на кого?" -> кратък член.

Целият код, примери и напътствия да следват конвенциите, решени по време на първата сре а:

• { след for / if / функция - на същия ред.
• camelCase за именуване на променливи, примери: firstName, totalSum.
• camelCase за именуване на функции, пример: printOutput(string output).
• Индентация: 4 spaces.
• Интервали около операторите: int sum = b + c;.
• Форматиране на функции:

int sum(int a, int b) {
    return a + b;
}

• Форматиране на цикли:

for (int i = 0; i < 5; i++) { 
}

• Форматиране на проверки:

if ((a < b) && (c < d)) {
}

• Пишем без auto, но го споменаваме в темата за "променливи".
• Ползваме endl за край на ред, пример: cout << val << endl;.
• Ползваме навсякъде using namespace std; (не ползваме std::cout), НО да се обяснят и двата начина.

Заглавията в български език са в стил "Главна буква, следвана от само малки". Коректен пример:

"Входна единица".

Некоректен пример:

"Входна Единица".

Заглавията, които съдържат въпрос, трябва да завършват на "?", примерно това е грешно заглавие:

"Какво представлява while цикълa".

Това е правилно заглавие:

"Какво представлява while цикълът?"

И трябва да е с пълен член, защото отговаря на въпроса "кой?"

В / във и с / със. В български език се ползва предлог "във" единствено, когато следващата дума започва с буквата "в". Аналогично "със" се ползва, когато следващата дума след предлога започва с буквата "с". Коректен пример:

"на входа се подават x1, y1, x2, y2, x3, y3 в този си ред".

Грешен пример:

"на входа се подават x1, y1, x2, y2, x3, y3 във този си ред".