Оригінал статті ви можете знайти тут http://www.forth.org/forth_coding.html

Створений Пол Е. Беннетт з технології управління транспортом ТОВ

Дата оригіналу: 23 березня 1995 року

Дата останньої зміни: 28 грудня 1996 року (для групи «Формула інтересів» та comp.lang.forth)

Наступний текст надається загальнодоступному для некомерційного використання всіма програмами з Forth. Некомерційні для цілей цього документа означають не для отримання прибутку відтворення цього тексту. Комерційні організації можуть використовувати цей текст як основу власних процедур кодування, якщо вони не продають такі процедури поза їхніми організаціями.

Як і було обіцяно, я публікую правила кодування, які були змінені з мого власного стандарту компанії та з деякими змінами, що застосовуються до нещодавнього європейського контракту. Ці правила були додатково відредаговані, щоб розглянути пару більш конкретних питань. Інформація про стек зображення налаштована таким чином, що автоматичні інструменти можуть створювати записи глосарію. Для цих форматів стек форматів потрібно буде визначити додаткові слова в системах, якщо вони використовуються у вихідному коді. Вони є:

(S приймає функцію (якщо не використовується з глосарічним інструментом

(R приймає функцію (якщо не використовується з інструментом глосарій

(G приймає функцію (якщо не використовується з інструментом глосарій

Я, як тільки зможу, надсилати деякий код, який дасть уявлення про те, як було призначено інструмент генерації глосарію. Я пишу це зараз (одне з тих завдань, які я мав намір зробити вже давно).

ЗМІСТ

1 ВСТУП
2 СФЕРА ЗАХИСТУ
3. СПИСОК ДОКУМЕНТІВ
4 СЛОВНИК ТЕРМІНІВ
5 ПРОСТОРАННІ СТАНДАРТИ ВИКОРИСТОВУЮТЬСЯ
6 ПРОГРАМНЕ ЗАБЕЗПЕЧЕННЯ ОРГАНІЗАЦІЯ
6.1. ІНФОРМАЦІЯ ПРО АУДИТ ДОКУМЕНТА
6.1.1. ТИПОВИЙ БЛОК
6.1.2. ВСТУПНИЙ ПЕРЕХІД
6.1.3. ЕКСПОРТ
6.1.4. ЕКОЛОГІЧНІ ВІДПОВІДІ
6.1.5. ІСТОРІЯ ПЕРЕГЛЯДУ
6.2. ВИЗНАЧЕННЯ КОД ДЖЕРЕЛА
6.2.1. ВКЛЮЧАЄ
6.2.2. КОНСТАНТИ І змінні
6.2.3. ФУНКЦІЇ
7 СТИЛЬ ПРОГРАМУВАННЯ
7.1. КОНВЕНЦІЇ НА ІМЕНІ
7.1.1. Дозволені персонажі в іменах
7.1.2. ІМ’Я КОНСТРУКЦІЯ
7.2. ВИЗНАЧЕННЯ ПЛАНУ
7.2.1. ПОЛІТИКА ВІДКРИТТЯ
7.3. СТРУКТУРА
7.4. РІЗНИЙ ЗАХОДИ, ВІДПОВІДІ ДО РЕЖИМУ
7.5. АРГУМЕНТИ СТЕК ЕФЕКТИ
7.6. СЛОВА, ЩО ПОВЕРНУТИ РІЗНИМ НОМЕРАМИ ПУНКТІВ
7.7. КОНТРОЛЬНІ СТРУКТУРИ
7.8. ВИКОРИСТАННЯ ЛІЦЕРАЛЬНИХ ЦІННИХ І «МАГІЧНИХ НОМЕРІВ»
7.9. СЛОВНИЙ ТЕКСТ
7.10. ПАРАМЕТРИ, КОНСТАНТИ І ЦІННОСТІ
8 ДОПОМОГА ДЛЯ ПЕРЕВІРКИ ТА ПІДТВЕРДЖЕННЯ
9 СЕРТИФІКАЦІЯ ПЗ

1. ВВЕДЕННЯ

Мета створення програмного забезпечення полягає в тому, щоб написати всю документацію як частину вихідного коду у формі коментарів. Зовнішня документація повинна бути автоматично виведена з вихідного коду. Щоб увімкнути це, потрібно, щоб усі джерела відповідали стандартному стилю компонування та кодування та коментування.

Мета цього стандарту полягає у спрощенні завдання перегляду та сертифікації програмного забезпечення. Для досягнення цілей цього стандарту передбачені певні стилі макета, стилю програмування та коментування джерела програмного забезпечення.

2. СФЕРА ЗАХИСТУ

Цей документ містить керівництво щодо побудови вихідного коду програмного забезпечення для досягнення цілей безпеки, якості та цілісності Europay International. Наслідком цього керівництва повинно стати джерело програмного забезпечення, яке легко прочитати та зрозуміти, представлене у стандартному форматі. Цей документ призначений для постачальників додатків і постійно рекомендується постачальникам ядра.

3. ОСНОВНІ ДОКУМЕНТИ

  1. ANS X3.215 «Інформаційні системи — мова програмування — Форт» 1994
  2. ISO / IEC 15145 «Інформаційні технології — мови програмування — FORTH» (= ISO / IEC DIS 15145: 1995) 1995
  3. «Подумавши» Броді, Лев. 1984 (ISBN 0-13-917568-7)

4. ГЛОСАРІЙ ТЕРМІНІВ

У цьому документі використовуються наступні терміни:

ANS — Американський національний стандарт

Застосування — Програмне забезпечення, яке реалізує системний продукт. Програми складаються з модулів.

BS — Британський Стандарт

EN — Comite, Europe, de Normalization

МВЦ — Міжнародна електротехнічна комісія

IOR — Результат операції введення / виводу (значення прапора, яке передає інформацію про тип несправності, якщо така є, з операції з пристроєм вводу / виводу).

ISO — Міжнародна організація стандартів

Лексикон — Слова модульного компонента стають видимими для інших модулів.

Бібліотека — Набір високорівневих програмних функцій з опублікованим інтерфейсом.

Об’єкт — Посилання в цьому документі на об’єкти відносяться до методів-об’єктів, а не до даних-об’єктів. Об’єкти методу можуть бути пов’язані з конкретним стандартним методом виконання завдання.

Текстовий набір — Набір визначень Forth, згрупованих під іменем, що вказує на якийсь спільний аспект, як правило, їх загальну функціональну область.

5. ПРИКЛАДНІ СТАНДАРТИ ПРОГРАМНОГО ЗАБЕЗПЕЧЕННЯ

Вся програма повинна відповідати визнаним стандартам для мови, в якій описано кодування. Міжнародні, європейські та національні стандарти, прийняті як застосовувані, є ISO, IEC, EN, ANS та BS. Стандарти компанії, де створюються специфічні стандартизовані практики, мають перевагу. У специфікаційних документах зазначаються стандарти, які застосовуються.

6. ОРГАНІЗАЦІЯ ПРОГРАМНОГО ЗАБЕЗПЕЧЕННЯ

Лістинг програмного забезпечення повинен використовувати формат з файлів шаблонів (TEMPLATE.FTH для текстових файлів або TEMPLATE.SCR для файлів екрана), який забезпечує основну основу для необхідної інформації про відстеження документа.

Лістинги повинні бути структуровані ієрархічно, як добре написана та організована книга. Кожен запис повинен чітко відноситись до специфікаційного документа, з якого складаються вимоги. Автор лістингу програмного забезпечення повинен надати чіткі засоби для відстеження здатності програмного забезпечення до специфікації його вимог, де це можливо. Сюди входить текст введення глосарію, подальші негласорарні описи та посилання на розділи або абзаци документа специфікації.

6.1. ІНФОРМАЦІЯ ПРО АУДИТ ДОКУМЕНТА

6.1.1 ЗАГАЛЬНИЙ БЛОК

Блок заголовка містить імена компанії та розділи авторських прав у шаблоні списку. Заголовок — це вбудована форма, яка вимагає заповнення стандартизованої інформації. Ця інформація визначає частину трасування для специфікації вимоги та дає основні відомості про лістинг.

6.1.2 ВСТУПНИЙ ПЕРЕХІД

Кожен вихідний файл буде містити лексикографічно повний набір функцій для області застосування. Вступний звіт коротко опише зміст файлу. Це має обмежуватися в максимум 100 слів або до першої сторінки розбитись у текстовому файлі та на одному екрані у файлі блоків. Текст вступу може бути скопійований з відповідного документа специфікації, якщо такий текст стисло описує вміст списку.

6.1.3 ЕКСПОРТ

Він повинен містити список функцій, доступних для використання іншими модулями. Це не обов’язково весь список функцій, визначених у списку. Деякі функції в цьому списку можуть бути придатними лише для місцевого використання.

6.1.4 СЕРЕДОВИЩЕ ВІДПОВІДАЛЬНОСТІ

Тут повинні бути перелічені специфічні нестандартні слова або набори слів, необхідні. Вона також повинна визначати конкретні вимоги до апаратних засобів та їх механізми доступу до функцій, зазначених у переліку.

6.1.5 ІСТОРІЯ ПЕРЕГЛЯДУ

Історія перегляду повинна бути вказана в зворотному хронологічному порядку. Кожен елемент перегляду повинен бути класифікований для його ефективності (як основного, малого чи тривіального) в описі змін (внесених). Правила очищення історії перегляду повинні бути сформульовані шляхом обговорення.

6.2. ВИЗНАЧЕННЯ КОД ДЖЕРЕЛА

6.2.1. ВКЛЮЧАЄ

Перевірте список команд, щоб включити всі інші джерела програмного забезпечення, необхідні для побудови цього модуля.

6.2.2. КОНСТАНТИ І змінні

Список констант і змінних, які спочатку використовуються в поточному вихідному файлі або на екрані.

6.2.3. ФУНКЦІЇ

У Forth функції називаються підпрограмами, також відомі як Words. Назва кожної функції повинна бути така, що описує функцію, яка є практичною. Функції можуть бути визначенням колонки або визначенням асемблерних кодів.

Кожне визначення функції має форму наступного, див. Також визначення двокрапки у довідковому документі 1.

: (S input-stack — output-stack) (R — )

(G descriptive glossary text)

f1 f2 ( interim stack picture) \ programmers explanatory comment

.. fn ;

Де:
: — починається визначення кишечника.
— це назва функції.
(S — це коментар стеки даних.
input stack — це список елементів стовпчика вводу, розділених пробілами між кожним елементом.
output stack — це список стовпчиків вихідних елементів, що повертаються функцією, з пробілами між кожним елементом.
(R — є коментарем зі зворотним зв’язком.
(G — це коментар до тексту в глосарії.
f1 f2 .. fn — є попередньо визначеними функціями.
interim stack picture — Очікуваний проміжний стан функцій складається з елементів. (S та (R можуть бути використані для відмінності даних і повернення стеків.
programmers explanatory comment — Короткий коментар про безпосередню лінію вихідного коду, який пояснює, що відбувається.
; — кінець значення колони.

7. СТИЛЬ ПРОГРАМУВАННЯ

7.1. КОНВЕНЦІЇ НА ІМЕНІ

Імена для визначення рядка коду стосуються функціональних аспектів визначення таким чином, що відображає яку функцію виконує визначення, а не як виконується функція. Імена мають бути англійськими та коротшими, достатньо довгі для ясності, але не більше 31 символу.

7.1.1. Дозволені персонажі в іменах

Наступний список графічних символів, витягнутих з довідкового документа 1, є єдиними символами, дозволеними для використання в Форт-дефінах.

!»#$%&()*+,-./ digits 0-9:;<=>? @ ALPHA A-Z \^_ alpha a-z {|}~
Вони представлені кодами символів ASCII 0x21 до 0x7E включно.

Використання символів керування або будь-яких графічних символів за межами вказаного діапазону в межах назв визначень заборонено.

7.1.2. ІМ’Я КОНСТРУКЦІЯ

Слова для програм складаються з двох типів: тих, які містяться в модулі, а ті, які не є. Використання модульних конструкцій настійно рекомендується для коду програми. Подібні об’єкти повинні міститися в межах одного модуля. Схожості слід судити за типом об’єкта, який потрібно обробляти. Вони, як правило, ґрунтуються на стандартах або письмових процедурах.

7.2. ВИЗНАЧЕННЯ ПЛАНУ

Тіло визначення має бути побудоване з повагою до фрази, втіленої в межах природної англійської мови. Воно використовує слова, якщо б вони були сукупністю іменників або дієслів з прикметниками та прислівниками як модифікаторів. Білий простір у визначенні є важливим аспектом читабельності вихідного тексту.

У ідеалі визначення має бути коротким. За жодних обставин визначення не повинно перевищувати більше однієї сторінки (приблизно 50 рядків з 12pt тексту, що допускає розміщення заголовків і нижніх колонтитулів) і не повинно займати більше 80 символів у ширину.

7.2.1. ПОЛІТИКА ВІДКРИТТЯ

Колонка визначення рядка починається в лівому краю по відношенню до лівого краю сторінки. Основна частина визначення має бути відступною однією вкладкою, яка повинна бути встановлена в 3 символьних пробілів. Кожна керуюча конструкція повинна відступити далі від цього на 3 символи для кожного наступного рівня відступу, див. Розділ 7.7 для максимальної глибини керуючої структури. Зупинки вкладок повинні бути реалізовані як символи жорсткого простору.

7.3. СТРУКТУРА

Всі програми повинні відповідати правилам структурованого програмування. Кожному визначенню дуже рекомендується мати лише одну точку входу і лише один пункт виходу, за винятком випадків, коли виникають помилки, що вимагають відновлення стану системи. Винятки та умови помилки, для яких не передбачено IOR, обробляються лише стандартними механізмами обробки виключень CATCH і THROW та будь-якими логічними розширеннями цих слів.

7.4. РІЗНІ ЗАХОДИ, ВІДПОВІДІ ДО РЕЖИМУ

Якщо визначене слово призначене для виконання різних дій, залежно від того, чи це в компіляції чи виконанні, або в будь-якій іншій державі, ефекти стека для кожного стану повинні бути вказані на окремі рядки, а стан, до якого відносяться ефекти стеку, позначено в коментарях . Порядок переліку бажаних — Компіляція, а потім виконання.

: ARRAY

CREATE (S x-size y-size —) \ compiling

…… ………

DOES> (S x-offset y-offset — a-addr) \ executing

…… ……… ;

7.5. АРГУМЕНТИ СТЕК ЕФЕКТИ

Всі аргументи ефекту стек даних повинні бути прокоментованими для всіх визначених слів, навіть якщо є нульовий ефект і аргументи не споживаються або не виробляються словом. Аргументи ефекту стека вказують на те, що параметр типу переданий, якщо такий є. Номенклатура «Типи даних» таблиці в довідковому документі 1 рекомендується для позначення типу даних параметра стека. Інша номенклатура може бути використана, але при використанні вона має бути якомога індикативною, наскільки це практично. Пробіл повинен розділяти елементи стек. Перевищення номенклатури типу даних допустимо.

Ефекти на стек повернення повинні бути вказані, коли використовуються слова, які впливають на стек повернення, такі як> R, R> та R @.

7.6. СЛОВА, ЩОБ ПОВЕРНУТИ РІЗНІ НОМЕРИ ПУНКТІВ

Слова, які повертають різні числа елементів, повинні мати обидві версії своїх ефектів стека, зазначені на окремих рядках, наприклад:

: ?RX (S — char true) \ character present

(S — false) \ character not present

…… ……… ;
Додаткові коментарі можуть з’являтися право коментарів ефекту стека, щоб надати додаткові пояснення. Використання таких слів у додатку повинно бути мінімізованим.

7.7. КОНТРОЛЬНІ СТРУКТУРИ

Контрольні структури включають всі вимоги розгалуження потоку керування програмою, включаючи цикли. Максимальна глибина гніздування структур управління в рамках єдиного визначення дуже рекомендується обмежуватись трьома. Вимоги щодо більш ніж двох рівнів гніздування зазвичай вказують на необхідність розгляду подальшої факторизації.

7.8. ВИКОРИСТАННЯ ЛІЦЕРАЛЬНИХ ЦІННИХ І «МАГІЧНИХ НОМЕРІВ»

Використання «магічних чисел» або літералів в межах тіла визначення функції не допускається. Всі необхідні номери повинні бути отримані або містяться в заздалегідь визначених константах. Це спрощує процес внесення змін до цих значень, змінюючи саме значення, що зберігається у відповідній константі.

7.9. СЛОВНИЙ ТЕКСТ

Усі слова повинні супроводжуватись ясним, стислим пояснювачем тексту у формі текстового введення глосарію, який може бути пізніше вилучено автоматизованими інструментами, які допомагають у створенні документації користувача. Текст глосарія має відноситися до оголошених ефектів стеку слова, якщо такі є, і оголосити будь-які винятки, які можуть бути сформовані функцією для недійсних параметрів.

7.10. ПАРАМЕТРИ, КОНСТАНТИ І ЦІННОСТІ

Змінні та константи — це способи забезпечення заповнювачів іменованих номерів. Хороший дизайн програми, що входить до складу Forth, мінімізує залежність від використання КОНСТАНТУВАННЯ чи ЗМІСТНОСТІ, наскільки це практично. Однак там, де вони потрібні, наступні рекомендації допоможуть їм використовувати їх.

Змінні, константи та значення повинні визначатися локально, де вони використовуються вперше.
Завжди ініціалізуйте VARIABLE до деякого значення, коли його спочатку оголосили.
Для фрагмента коду, в якому використовується змінна або значення (що може мати справу з певною функцією), створюйте слово ініціалізації для кожного функціонального розділу, це зменшить розмір слова ініціалізації верхнього рівня та керування кодом легше
Завжди виконуйте ініціалізацію верхнього рівня за допомогою слова GO або RUN.
Таким чином, якщо частини ієрархії використовуються в декількох додатках, то ви не пропустите жодного, якщо ви щось зміните і створите нову змінну, яка потребує ініціалізації.

8. ДОПОМОГА ДЛЯ ПЕРЕВІРКИ ТА ПІДТВЕРДЖЕННЯ

  • Тестові скрипти
  • Контрольні списки
  • Перевірені дані тесту
  • Випадкові дані випробувань

9. СЕРТИФІКАЦІЯ ПЗ

Сертифікація програмного забезпечення — це декларація про те, що все програмне забезпечення, описане в списку джерел, завершено, виконує свої функції без помилок, є стійким до недовірливих стимулів і не має невирішених посилань. Сертифікат також заявляє, що виконувані функції відповідають вимогам, описаним у специфікаційному документі.

Сертифікація застосовується в багатоетапному процесі, який формально аналізує отриманий код у режимах статичного та динамічного тестування відповідно до сценарію тестування, розробленим для підтвердження відповідності. Отже, всі процедури сертифікації вимагають отримання гарантій, які вони дають про програмне забезпечення, з повної та ретельної перевірки, яка відстежує процес розробки та розробки від специфікації до кінцевого продукту. З цієї причини системи керування версіями та змінами, що використовуються вручну або автоматично, повинні використовуватися для забезпечення повного ознайомлення з якісною основою для всіх продуктів.

Written by