ПРОЧТИМЕНЯ

README — такие файлы обычно создаются в директориях с целью ввести в курс что тут лежит и для чего.

Не скажу, что я в абсолютно каждом директории оставляю такой файл, но я стараюсь снабжать директории своих многочисленных проектов этими файлами. Кроме того у меня очень много директориев с данными, снятыми с разных измерительных установок. Со временем всё забывается. Человеческая память старается избавиться от редко-используемой информации. Поэтому через несколько лет бывает очень трудно вспомнить где, что, для чего я это делал. И только спасительный README-файл помогает мне быстро восстановить картину мира.

Обычно я стараюсь в таких файлах ответить на такие вопросы как:

— что за проект лежит в директории
— краткое назначение проекта
— в какой среде (Операционке) проект создан
— на каком компе, если это важно для проекта
— какая последняя версия проекта
— дата последнего изменения
— Какой тип микроконтроллера использован
— тактовая частота
— если это AVR, то указываю фьюзы
— привожу распечатку вывода утилиты size (размеры секций памяти)

Если это директорий с данными, полученными с установки, то освещаю следующие вопросы:
— что за данные тут лежат
— когда получены данные
— где (географическое место)
— кем получены
— при каких (или в каких) условиях получены данные: температура, скорость ветра, давление, глубина погружения, солнечная активность и т.д.

Это не необязательный список вопросов. Все зависит от типа проекта или директория. Нужно только осознать необходимость сделать запись, а не писать много и через силу. Нужно просто ответить в этом файле себе самому на самые простые вопросы. Это основное требование к README-файлу.

В книге, которую я сейчас с упоением читаю («Beginning Python Visialization: Crafting Visual Transformation Scripts» Shai Vaingast, 2009), автор тоже уделил немного внимания README-файлу. Вот пример его файла:

Данные записаны с GPS-приемника, подсоединенного к нотику Lenovo T60.
Данные были получены через последовательный порт и записаны в плоский текстовый csv-файл.
Измерения были сделаны с целью определить скорость и время в пути.
Данные получены Шайем Вайнгастом (автором)
Дата получения данных: 2008 год, см. дату создания файлов.

Как видите, всё очень несложно, и скорее всего для создания этого файла автору потребовалось всего две-три минуты. Но зато какая будет польза от такого файла через год-другой!

Иногда в директории полезно иметь такие файлы как HISTORY и TODO. В первом сохраняется краткая летопись развития проекта. Это иногда бывает полезно прокрутить назад на несколько месяцев и начать новую ветку проекта. У меня такое было несколько раз. Второй файл — это файл для напоминания что необходимо сделать — дописать какую-нибудь функциональность, что-то переделать, изменить алгоритм, пофиксить ошибки или просто зафиксировать свои хотелки и творческие мысли по проекту.

Я не утверждаю, что это всё это нужно делать в обязательном порядке. Каждый решает сам — надо ему это или нет. Я просто делюсь положительным решением своих проблем. Мне часто приходится перепрыгивать с одного проекта на другой. И каждый раз приходится вспоминать — на каком шаге я остановился в разработке этого проекта. Эти файлы мне очень помогают войти в контекст проблемы, и я не считаю время на их создание потерянным. Не будь этих файлов я бы дольше тупил в монитор в поисках ответа.

Реклама

Добавить комментарий

Заполните поля или щелкните по значку, чтобы оставить свой комментарий:

Логотип WordPress.com

Для комментария используется ваша учётная запись WordPress.com. Выход / Изменить )

Фотография Twitter

Для комментария используется ваша учётная запись Twitter. Выход / Изменить )

Фотография Facebook

Для комментария используется ваша учётная запись Facebook. Выход / Изменить )

Google+ photo

Для комментария используется ваша учётная запись Google+. Выход / Изменить )

Connecting to %s