READMEs should be great places to start when reading code.
The first thing to look at when trying to spin up on new code should be the project’s README file. Most projects now will have a useful readme.
Contents
What should be in a readme file?
First, there should be some brief description of what the thing is. What the project does, and generally where it fits in the overall scheme of things. For example, if the project is a frontend UI, it should state that it is a front end UI, and that it communicates with the backend API.
Notable landmarks in the code. Where are the generally interesting bits of code? Entrypoints perhaps, or packages that contain significant pieces of code. Perhaps even note any particularly tricky pieces of code that might trip up newcomers
How do I build the code? Obviously this will be of interest to anyone unfamiliar with the code. This could just be pointing out the obvious, such as this builds with Maven (when there is a very standard pom.xml file and directory format). But it would also be useful to call out the more non-obvious items, such as what version of Java is used, any dependent services that need to be running. It is especially useful to give a view of how the code is built when there may be multiple builders present, such as Maven and Gradle, since it definitely is not obvious what is going on in cases like this.
Contribution guidelines. Is there anything in particular that should be included in pull requests? Do you assign certain reviewers? Any guides for test code coverage? You may pull this out into a separate file, or wiki page. But make sure to link to it here. This is also a good place to put any kind of code formatting rules and guides.
It is also useful to call out the pieces that go around the code, such as the URL to a build job. Or even how this is deployed in various environments. Call out if this is a Docker container, or a deploy to a Kubernetes cluster.
Properly Formatted
Of course, the README file should be properly formatted. Make sure you follow the markdown format, if appropriate. Readme files that are hard to read are as good as useless. Also do your best to eliminate typos, abbreviations, and other jargon that may creep into here. Remember that the people that will be reading this file are already unfamiliar with the code.