Цей список має допомогти вам писати якісні програми.

Рафаель Фінкел, 17.08.2005

  • Ідентифікатори: переконайтеся, що всі ваші ідентифікатори є значимими.
    1. Однобуквенні ідентифікатори майже завжди позбавленні сенсу.
    2. Такі імена як flag і temp рідко бувають змістовними. Замість flag, розгляньте назву логічного умови яку він перевіряє, наприклад, valueFound.
    3. Розгляньте ідентифікатори, що складаються з багатьох слів, як от nameIndex. Довгі (в розумних  межах) ідентифікатори, як правило, лешко зчитаються.
  • Чисті літерали: у своїй програмі уникайте будь-яких цифр окрім 0 і 1, і рядки, без «», крім випадків, коли ви визначаєте константи.
    1. Не використовуйте цілочисельний літерал як межу масиву.
    2. Не використовуйте цілочисельний літерал як параметр run, такий як час очікування або номер порту.
    3. Не використовуйте цілочисельний літерал для вибору пунктів меню.
    4. Не використовуйте цілочисельний літерал для вимірювання розміру рядка або деяких даних; використовуйте sizeof()та strlen() у C, і C++ та .length() і .size у Java.
    5. Не використовуйте літеральний рядок для імені файлу. Тим не менш, ви можете виводити літеральні рядки.
    6. Не використовуйте цілочисельний літерал для індексування в масив, що містить неоднорідні дані.
    7. Не позначайте ідентифікатор з ім’ям, що означає літерал, наприклад, «тридцять».
  • Модуляризація: програма побудована із взаємодіючих компонентів.
    1. Не ставте весь ваш код в  main() програму.
    2. Власне кажучи, не робіть взагалі програму занадто довгою. Якщо вона буде більшою ніж 50 рядків, це буде занадто багато.
    3. Якщо ви повторюєте код декілька разів, обміркуйте, що буде працювати краще:  цикл чи, можливо, підпрограма.
    4. Якщо виявиться, що ви відступаєте занадто далеко, швидше за все, ви не використовуєте підпрограми, коли потрібно.
    5. Не переробляйте бібліотечні програми (якщо це не потрібно для вашого завдання). Перегляньте посібники, щоб дізнатися, наприклад, про sprintf() і atoi()
    6. Використовуйте файли заголовків у C та C ++ (файли заголовків мають назви, що закінчуються на .h), щоб визначити всі константи, необхідні для декількох файлів, і встановити всі підпрограми, експортовані між файлами. Але не ставте основну частину підпрограм у файли заголовків (вбудовані підпрограми є рідкісним виключенням).
  • Форматування: Ваша програма повинна легко зчитуватись.
    1. Ознайомтеся тут http://geosoft.no/development/javastyle.html  із чіткими рекомендаціями щодо форматування та інших питань презентації. Ця довідка створена спеціально для Java, проте вона також буде цінною і для іншим мов програмування.
    2. Спробуйте обмежити всі ваші рядки до 80 символів; з історичних причин, багато людей переглядають код у вікнах із 80-ма стовпчиками.
    3. Не використовуйте обидві вкладки та пробіли для відступу, оскільки не всі текстові редактори обробляють вкладки рівно по 8 пропусків.
    4. Виконуйте правильний шаблон відступу, який відображає структуру керування програмою.
    5. Не додавайте багато порожніх рядків у вашу програму. Достатньо буде лише одного порожнього рядка між підпрограмами.
    6. Різні операційні системи розмежовують лінії різними способами. Якщо ви рухаєтесь між Win32 (який використовує \ r \ n), Unix (який використовує \ n) і MacOS (який використовує \r), переформатуйте свій файл, щоб використовувати послідовний метод завершення.
    7. Не встановлюйте виконуваний біт (Unix) на вихідні файли.
  • Кодування: ви хочете, щоб ваш код був чітким, легко супроводжувався, і був ефективний. Деякі представлені правила є дуже специфічні; інші — більш загальні.
    1. Не використовуйте послідовність if операторів, які не мають else, якщо тільки один може збігатися; використовуйте else if.
    2. Якщо ви хочете класифікувати текстовий ввід, не перераховуйте можливі перші символи.
    3. Використовуйте оператори зміщення замість множення для побудови бітових шаблонів.
    4. У операторі switch, завжди перевіряйте типовий випадок. Аналогічним чином, у послідовності операторів if-then-else , використовуйте останній else.
    5. Всі системні виклики можуть вийти з ладу. Завжди перевіряйте код повернення та використовуйте perror(), щоб повідомити про несправність.
    6. Булеві типи повинні завжди використовувати boolean тип в Java, bool у C ++ та 0/1 цілі числа у C. Не використовуйте символи t і f, і не використовуйте -1 і 1.
    7. Використовуйте цикли для ініціалізації структур даних, якщо це можливо.
    8. Використовуйте кожну змінну та кожне поле структури для конкретної однієї цілі. Не перевантажувати їх, якщо немає вагомої причини для цього.
    9. Не використовуйте однаковий ідентифікатор для типу, змінної та імені файлу, навіть якщо ви зробите їх великими літерами. Це занадто дивно.
    10. Якщо ви модифікуєте дані за допомогою htonl() або подібної програми перед передачею мережі, не змінюйте одразу дані. Створіть другу структуру даних.
    11. Спробуйте не використовувати глобальні або нелокальні змінні. Затвердіть кожну змінну у найменшому масштабі. Є законне використання нелокальних змінних, але переконайтеся, що вони дійсно вам потрібні.
    12. Програми Shell, Perl і Python повинні мати свою #1 лінію, як перший рядок файлу; в іншому випадку, ця лінія є просто коментарем.
    13. Намагайтеся уникати кодування особливих випадків. Ви часто можете використовувати псевдо-дані чи інші методи структури даних, які дозволяють вам об’єднати спеціальні випадки разом із  звичайними.
  • Компілятори: дозвольте їм допомогти вам знайти помилки
    1. Завжди налаштовувати компілятори з усіма попередженнями. Для C і C ++ використовуйте -Wall . Для Java, використовуйте -Xlint:all -deprecation та використовуйте pmd  програму, щоб отримати пропозиції для кращого стилю. Для Python використовуйте -t -W all.
    2. Усі програми Perl повинні працювати з -w прапором і повинні мати use strict. Всі сценарії Perl cgi-bin теж повинні мати прапор -T.
  • Утіліта make: використовуйте її, і використовуйте добре.
    1. Makefile завжди повинен завжди мати «чистий» рецепт, який видалить всі файли, які можуть бути відновлені іншими рецептами в make-файлі, включаючи об’єкт і виконувані файли.
    2. Якщо у вашому проекті є декілька вихідних файлів, makefile повинен генерувати необхідні файли об’єкта (.o) і пов’язувати їх разом.
    3. Makefile повинен бути написаний таким чином, що якщо ви запускаєте make двічі поспіль, то другий цикл не здійснює перекомпіляцію.
    4. Кожен рецепт повинен створити файл, зазначений у його завданні.
    5. Кожен рецепт повинен використовувати кожен файл, вказаний у його переліку умов.
    6. Навчіться застосовувати правила для завдань, таких як .c.o, щоб уникнути повторюваних файлів make.
    7. Якщо у вас є лише один вихідний файл C або C ++, виконуваний файл повинен мати однакове ім’я (без розширення .c або.cpp).
    8. Переконайтеся, що ви вказали всі .h файли як передумови, де вони потрібні. Подумайте про використання makedepend для створення переліку умов для себе.
  • Документація: це не просто для грейдера. Це також допомагає вам у написанні програми!
    1. Додайте документацію коли ви пишете програму. Ви завжди можете модифікувати її, адже ваша програма змінюється.
    2. Включіть зовнішню документацію: Як створюється і запускається програма, і для чого вона необхідна ? Зовнішня документація може бути в окремому файлі; для невеликих проектів це може бути коментар у єдиному вихідному файлі.
    3. Додайте внутрішню документацію: які алгоритми та структури даних ви використовуєте? Огляд може бути в окремому файлі, але, як правило, внутрішні документи розміщуються на конкретних процедурах, деклараціях та етапах, які той описує.
    4. Перевірте вашу програму та документацію на наявність орфографічних помилок. Здавати роботу з помилками зовсім неввічливо і свідчить про неуважність до деталей.
    5. Перевірте всю вашу документацію (та вихідні повідомлення) на граматичні помилки.
    6. Програми значно легше зчитуються, якщо ви поставите короткий коментар щодо закриваючих дужок. Наприклад, фігура, яка закриває умову, може мати подібний коментар «якщо значення виглядає добре». Скобка, яка закінчує цикл, може мати коментар «для кожної лінії вводу». Кінцева фігура, що закриває процедуру, може мати коментар, просто називаючи процедуру. Кінцева фігура, що закриває клас, може мати коментар, що називає «клас», а потім ім’я класу.