ЗМІННА СЕРЕДОВИЩА
FILE Зберігає ім'я файлу, отримане з командного рядка.
ОПИС
НАВІЩО НАМ ПОТРІБНИЙ stripc?
У більших проектах по розробці програмного забезпечення требу
ется звичайно багато часу для роботи з документацією. Є програм
ные файли для документування, функціональні специфікації для написа
ния програм і, нарешті, керівництва й довідкові карти, глоссарии,
покажчики й т.д. Справжній програмний код повинен мати свою собствен
ную убудовану документацію, інакше керування цим кодом стає
дуже важким.
Щоб уникнути плутанини, потрібно створити модель документації, а за
тим зробити її стандартом, якому повинні випливати всі програмісти.
Навіть якщо ця модель не буде абсолютно ідеальної, її наявність є
першим кроком по створенню середовища, який ви можете управляти.
Наступні два інструментальні засоби, які ми пропонуємо,
випливають моделі документації, описаної надалі тексті. Ця модель
послідовна й зрозуміла, її можна доповнити або змінити по вашому
розсуду.
ЩО РОБИТЬ stripc?
Stripc друкує тільки перший заголовний блок коментарів з
початку вихідного файлу мовою Си. Бажано, щоб цей блок содер
жал всю важливу інформацію про файл: його офіційне ім'я, для чого він
призначений, хто його створив, коли він був створений і т.д. Усередині файлу
може розміщатися одна або кілька функцій або навіть головна програм
ма. Ця модель припускає, що весь ваш код містить дуже мало глав
ных програм і багато незалежних модулів.
Розглянемо на модельному вихідному файлі, якого роду інформацію ми
повинні витягти з вихідних файлів.
/*
* Це заголовок, що документує, для файлу
* з вихідним кодом мовою Си.
* Він пояснює, що втримується у файлі (програми, функції,
* бібліотеки й т.д.) і ідентифікує проект.
*
*/ Це оцінка кінця заголовного коментарю.
^L Інструменти витягу застосовують control-L як роздільник.
/* Це заголовок, що документує, для головної частини програми.
* Головна позначка повинна пояснювати, що це за програма
* і що вона робить. Тут можуть бути також зазначені автор,
* дата й історія змін.
*/
main()
{
/* Тут перебуває головна Сі-програма */
}
^L
/* Це заголовок, що документує, для певної функції,
* яка за ним треба. Документується послідовник
* ность виклику, вхід і вихід і загальне призначення цієї
* функції.
*/
func(arg1,arg2)
int arg1;
char arg2;
{
/* Текст функції перебуває тут */
}
^L
/* Аналогічно, цей блок коментарів документує
* наступну функцію. Наявність документації разом з кодом
* скорочує обсяг накладних витрат при читанні й
* зміні коду.
*/
func(arg1,arg2)
int arg1, arg2;
{
/* Текст функції перебуває тут */
}
Як вказувалося раніше, функція main не обов'язкова й, імовірно,
зустрічається тільки в одному або двох файлах, залежно від виду прог
рамм, які ви пишете. Один файл може мати стільки функцій, скільки
ви хочете, але максимальне число, що рекомендується, - від однієї до трьох, в
залежності від того, як ці функції взаємозалежні. У кожному файлі
майте справу тільки з одною програмувальною ідеєю і її реалізацією.
При вивченні цієї моделі ви бачите, що забезпечується три рівні
документації. Заголовок на початку файлу витягає за допомогою stripc.
Цей заголовок ставиться до всього файлу в цілому. Заголовок на початку
головної програми ставиться до всієї програми й підтримується з по
міццю stripf. Заголовок для кожної функції ставиться до цієї функції.
Ці заголовки обслуговуються командним файлом stripf, що обсужда
ется нижче.
Відзначимо, що між функціями є прогін формату (символ
control-L коду ASCII). У попередньому лістингу ми вказали цю комбінацію
клавіш за допомогою символу ^L, щоб наші текстові процесори не произ
водили зайвих сторінок при форматуванні рукопису даної книги. Вам
потрібно в кожному випадку дійсно вводити control-L замість ^L при
розміщенні коментарів у ваших файлах і при уведенні вихідного коду даний
ного й наступних командних файлів. Символ прогону формату использу
ется в моделі заголовка для оцінки верхньої границі першої функції в
файлі й для прогону сторінок на друкувальному пристрої при чистовий
роздруківці, щоб кожна функція з'являлася на новій сторінці.
На початку кожної функції (перед main або перед ім'ям функції) діл
дружин існувати заголовок, що документує. Цей заголовок звичайно отра
жает найбільш недавні зміни в цьому модулі, і його можна вважати бо
леї достовірним, чим заголовок документа, що був надрукований
кілька тижнів або навіть місяців назад.
Входом для stripc є послідовність імен файлів з результат
ным кодом. Для кожного файлу в командному рядку перевіряється, існує
чи він і чи має розмір більше, ніж нуль байт. Якщо він не задовольняє
цим критеріям, то друкується повідомлення про помилку й перевіряється випливаю
щий файл. Кожний файл читається з першого байта, і в ньому шукається символь
ная рядок початку коментарю (/*). Коли вона знайдена, інформація до
символьного рядка кінця коментарю (*/) построчно виводиться в stdout.
Якщо праві символи не знайдені, нічого не друкується, але повідомлення про
помилці не виводиться, щоб не зіпсувати вивідну інформацію. Після того
як кожний файл оброблений, наприкінці друкується прогін формату, що
розбиває вивідну інформацію на розподіли-розділи-сторінки-розділи. Це застосовується в
основному, що коли документують заголовки дуже довгі й мають потребу в
візуальній розбивці.
Відзначимо, що "витяг" ("strip") тут і в наступних двох ути
літах означає не ВИДАЛЕННЯ, а копіювання відповідної інформації.
Ніяких змін у вхідних файлах не робиться.
Коли всі файли в командному рядку оброблені, командний файл за
вершается.
[
...]
Початок [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24] [25] [26] [27] [28] [29] [30] [31] [32] [33] [34] [35] [36] [37] [38] [39] [40] [41] [42] [43] [44] [45] [46] [47] [48] [49] [50] [51] [52] [53] [54] [55] [56] [57] [58] [59] [60] [61] [62] [63] [64] [65] [66] [67] [68] [69] [70] [71] [72] [73] [74] [75] [76] [77] [78] [79] [80] [81] [82] [83] [84] [85] [86] [87] [88] [89] [90] [91] [92] [93] [94] [95] [96] [97] [98] [99] [100] [101] [102] [103] [104] [105] [106] [107] [108] [109] [110] [111] [112] [113] [114] [115] [116] [117] [118] [119] [120] [121] [122] [123] [124] [125] [126] [127] [128] [129] [130] [131] [132] [133] [134] [135] [136] [137] [138] [139] [140] [141] [142] [143] [144] [145] [146] [147] [148] [149] [150] [151] [152] [153] [154] [155] [156] [157] [158] [159] [160] [161] [162] [163] [164] [165] [166] [167] [168] [169] [170] [171] [172] [173] [174] [175] [176] [177] [178] [179] [180] [181] [182] [183] [184] [185] [186] [187] [188] [189] [190] [191] [192] [193] [194] [195] [196] [197] [198] [199] [200] [201] [202] [203] [204] [205] [206] [207] [208] [209] [210] [211] [212] [213] [214] [215] [216] [217] [218] [219] [220] [221] [222] [223] [224] [225] [226] [227] [228] [229] [230] [231] [232] [233] [234] [235] [236] [237] [238] [239] [240] [241] [242] [243] [244] [245] [246] [247] [248] [249] [250] [251] [252] [253] [254] [255] [256] [257] [258] [259] [260] [261] [262] [263] [264] [265] [266] [267] [268] [269] [270] [271] [272] [273] [274] [275] [276] [277] [278] [279] [280] [281] [282] [283] [284] [285] [286] [287] [288] [289] [290] [291] [292] [293] [294] [295] [296] [297] [298] [299] [300] [301] [302] [303] [304] [305] [306] [307] [308] [309] [310] [311] [312] [313] [314] [315] [316] [317] [318] [319] [320] [321] [322] [323] [324] [325] [326] [327] [328] [329] [330] [331] [332] [333] [334] [335] [336] [337] [338] [339] [340] [341] [342] [343] [344] [345] [346] [347] [348] [349] [350] [351] [352] [353] [354] [355] [356] [357] [358] [359] [360] [361] [362] [363] [364] [365] [366] [367] [368] [369] [370] [371] [372] [373] [374] [375] [376] [377] [378] [379] [380] [381] [382] [383] [384] [385] [386] [387] [388] [389] [390] [391] [392] [393] [394] [395] [396] [397] [398] [399] [400] [401] [402] [403] [404] [405] [406] [407] [408] [409] [410] [411] [412] [413] [414] [415] [416] [417] [418] [419] [420] [421] [422] [423] [424] [425] [426] [427] [428] [429] [430] [431] [432] [433] [434] [435] [436] [437] [438] [439] [440]