▼Software Development
8.15.0.2
    contents    up   

—Read Me🔗

don't

Add README.md files to the project directory and each folder in the project repository. Also equip each milestone directory with such a file.

They do say that the best way to keep a secret on a computer is to place it in a file named README. Please prove us wrong.

The purpose of a README.md file is to help (1) you and (2) newcomers to explain and navigate the code base:

  • you can use it to provide an overview at the beginning of a code walk; and

  • a newcomer can read it to understand the organization of the code base and relationships among files that can’t be written down in plain code and that belong to none of the related files.

The first item in such a file explains the overall purpose of the project or directory.

The second one enumerates all files and the purpose of each file.

The third part explains how to run the internal unit tests and, for the milestone folders, specifies how to run the test harness for each milestone.

The last part explains ideas, concepts, and relationships among files. You may wish to use diagrams (ASCII or scanned-in napkin doodles) for this task to explain the relationship among the pieces, their interactions, etc;

In sum, the goal is to enable future maintainers—including older versions of yourself—to rapidly find their way around the code base, add unit tests for new bugs, fix a bug, or even add a feature—without necessarily understanding the complete code base.

If you haven’t seen any good examples, take a look at these. Some of these might be better fits to future workplace repos.

For our own Bazaar repo, we use scripts to generate the README.md files from a Readme.source file and the files and directories in a folder.

    contents    up