Skip to content

Latest commit

 

History

History
103 lines (66 loc) · 4.91 KB

main.adoc

File metadata and controls

103 lines (66 loc) · 4.91 KB

Unified Style Guide: Files and Directories 0.1

Table of Contents

1. Introduction

This document provides guidelines for naming computer files and directories. Following these guidelines should provide the following benefits:

  • Promote a consistent style over various use cases.

  • Aid organization of information.

  • Eliminate issues due to whitespace in file paths.

2. File Naming

Files use lowercase_underscore notation. All files should include an extension with the only exceptions being files that follow well-established and software-dependent conventions (e.g. Makefile). The extension should always be lowercase. See the following examples:

  • sample_file.txt

  • file_with_a_longer_name.jpg

When numbers are used to differentiate between files with similar names, the number should follow the name with a hyphen in between. See the following examples:

  • some_file-1.jpg

  • some_file-2.jpg

  • some_file-3.jpg

Any additional metadata added to the filename should prefix the proper name and be delimited with a hyphen. Metadata can be changed together and date information will typically go first. See the following examples:

  • followup-some_doc.txt - The followup text is metadata.

  • under_review-some_doc.txt - The under_review text is metadata.

When dates are added to the filename as metadata, use the YYYYMMDD basic format as defined in ISO 8601. Additional time resolution can be added if necessary but omit the T used in the ISO standard. See the following examples:

  • 20120101-my_file.txt - 1 January 2012

  • 201201012030-my_file.txt - 1 January 2012 at 8:30 pm

  • 20120101203045-my_file.txt - 1 January 2012 at 8:30:45 pm

To describe a file that contains information over a range of dates, use to to delimit the dates. See the following examples:

  • 20120101_to_20121012-finances.txt - 1 January 2012 through 12 October 2012

Filenames may contain capital letters when necessary for a specific use. See the following examples:

  • Makefile - Capital M by standard convention

  • _Build_All.bat - Capital letters and leading underscore by user convention.

Special metadata files use lowercase_underscore notation with double-underscores as prefix and postfix. See the following examples:

  • __dir_info__.txt

  • __arc_info__.txt

3. Directory Naming

Directory types fall into three general categories:

  • record - Used to organize/categorize contents. Typically the contents will not be frequently modified. Examples: photo albums, scanned documents, etc.

  • resource - Used to hold resources/assets of a project. Typically the contents are frequently modified. Examples: software source code, artwork, etc.

  • special - The use of these directories vary. Examples: backups, temporary files, output files, etc.

Record directories use LeadingCaps notation. See the following examples:

  • TaxRecords/

  • VacationPhotos/

Resource directories use lowercase_underscore notation. See the following examples:

  • src/

  • html_templates/

In either record or resource directories, hyphens are used to delimit date and other metadata applied as a prefix. See the following examples:

  • 2012-TaxRecords/

  • obsolete-css/

Special directories use lowercase_underscore notation with double-underscores as prefix. Double-underscores are used as a postfix unless the special name is being used as a metadata prefix. See the following examples:

  • __backup__/

  • __output__/

  • __output-log_files/

  • __temp__/

  • __temp-pictures/

4. Additional Guidelines

Special metadata prefixes can be added to a file or directory to give it additional meaning. These prefixes should be limited to one word with lowercase notation and leading double-underscores. See the following examples:

  • __temp-my_file.txt - Marks the file as temporary.

  • __output-my_file.txt - Marks the file as output.

Record directories may use metadata that follows the lowercase_underscore convention. See the following examples:

  • under_review-TaxRecords/

If necessary, record or resource directories can use a single underscore as a prefix to denote a differing level of significance from its sibling directories. See the following examples:

  • _SomethingSpecial/

If necessary, metadata can be applied as a postfix to files and directories. Typically, this is used to maintain alphabetical order of the proper name. See the following examples:

  • TaxRecords-under_review/

Unless necessary, avoid using additional periods in file or directory names. Periods are typically only used to separate the filename from the extension. A typical case that requires additional periods is when a version number is included in the file or directory name. See the following examples:

  • my_file-0.1.0.txt

  • SomeProject-v1.2/