Readme.txt против README.txt

33

Я только что разработал проект в Github, внес свои изменения и т. Д. Это заставило меня задуматься: в основном я вижу README.txt в проектах с открытым исходным кодом, а файл, который я редактировал, был Readme.txt. Это своего рода стандартизация или я должен был оставить все как есть?

Толга Озсес
источник
Все заглавные буквы, вероятно, начинались в MS-DOS, все строчные буквы, вероятно, из наследия Unix. Не уверен насчет заглавной первой буквы - возможно, корни Mac. В конце концов, это не имеет значения, кроме как из-за аккуратности или стиля.
Лоуренс

Ответы:

29

Заглавные буквы выделяются и делают файл легко видимым, что имеет смысл, потому что это, вероятно, первое, на что новый пользователь захочет взглянуть. (Или, по крайней мере, следовало бы посмотреть…) Как уже говорили другие, имена файлов, начинающиеся с заглавной буквы, будут перечислены перед именами в нижнем регистре в ASCIIbetical sorting ( LC_COLLATE=C), что помогает сделать файл видимым на первый взгляд.

Этот READMEфайл является частью набора файлов, который обычно ожидает найти пользователь пакета бесплатного программного обеспечения. Другими являются INSTALL(инструкции по сборке и установке программного обеспечения), AUTHORS(список участников), COPYING(текст лицензии), HACKING(как начать вносить свой вклад, может быть, включая список начальных точек TODO), NEWS(последние изменения) или ChangeLog(в основном избыточные с системы контроля версий).

Это то, что Стандарты Кодирования GNU должны сказать о READMEфайле.

Дистрибутив должен содержать файл READMEс общим обзором пакета:

  • название посылки;
  • номер версии пакета, или укажите, где в пакете можно найти версию;
  • общее описание того, что делает пакет;
  • ссылка на файл INSTALL, который, в свою очередь, должен содержать объяснение процедуры установки;
  • краткое объяснение любых необычных каталогов или файлов верхнего уровня, или другие подсказки для читателей, чтобы найти путь к источнику;
  • ссылка на файл, содержащий условия копирования. GNU GPL, если используется, должен находиться в файле с именем COPYING. Если используется GNU LGPL, он должен находиться в файле с именем COPYING.LESSER.

Поскольку всегда полезно стремиться к наименьшему удивлению ваших пользователей, вы должны следовать этому соглашению, если нет веских причин для отклонения. В мире UNIX расширения имен файлов традиционно использовались редко, поэтому каноническое имя файла READMEбез суффикса. Но большинство пользователей, вероятно, без проблем поймут, что имя файла README.txtимеет то же значение. Если файл написан на Markdown , имя файла вроде README.mdтакже может быть разумным. Избегайте использования более сложных языков разметки, таких как HTML, вREADMEфайл, однако, потому что это должно быть удобно читать на текстовом терминале. Вы можете указать пользователям руководство по программному обеспечению или его онлайн-документацию, которая может быть написана в более сложном формате, для получения подробной информации из READMEфайла.

5gon12eder
источник
20

Традиционно файл назывался README в верхнем регистре, потому что среды командной строки, которые используют алфавитный порядок, поместили бы файл в верхнюю часть. Это делает их легко видимыми в больших каталогах.

Скорее всего, это пережиток мира Unix / Linux, где вы будете загружать исходники, а затем создавать свое программное обеспечение. Наличие таких файлов, как README и INSTALL в верхней части представления «список содержимого каталога», упрощает просмотр того, что они есть, вместо просмотра всего содержимого из интерфейса командной строки. Тот же самый базовый принцип работает и для github (и на самом деле работает и в интерфейсах GUI, если подумать об этом, так что он все еще может быть достоинством)

Ни в коем случае не жесткое правило, но очень вероятно, что каждый делает это как привычку, потому что другие проекты делают это. Если нет явной причины НЕ делать этого, вам, вероятно, следует использовать все заглавные буквы только потому, что вы увидите, что они используются таким образом во многих других проектах. Это также имя по умолчанию, используемое Github при создании нового хранилища.

JDT
источник
Я всегда думал, что все заглавные буквы были формой акцента, очень похоже на то, как у вас есть разделы верхнего регистра на легальном языке.
Ларс Виклунд
1
В интерфейсе командной строки файлы, которые идут вверху списка, на самом деле те, которые сначала прокручиваются из поля зрения, поэтому иногда это наименее видимые файлы. Если только вы не делаете что-то подобное ls -l | less.
Марк ван Леувен
6

README обычно пишется в верхнем регистре. Таким образом, команда lsUnix поместила файл в начале списка каталогов (заглавные буквы идут перед строчными в порядке ASCII).

Manlio
источник
3
Это было исторической причиной, но, lsкак правило, не так на современных системах.
1
@ dan1111 Точно! Спасибо (просто чтобы попробовать ... LC_COLLATE="en_US.ascii" ; ls -lпротив LC_COLLATE="en_US.UTF-8" ; ls -l)
Манлио