How Do I Write Code That Others Can Easily Understand?
An Exploration of Inline Documentation and READMEs
In this article I explore the ways that computer programmers can make their code accessible to others through the use of well thought out written accompaniments to their code. I focus on inline documentation and README files.
I was drawn to this topic early on my journey into software engineering. Learning how to write code and share code is very interesting to me. My personal experience sharing documentation prior to becoming a software engineer included writing lesson plans, grant writing, editing documents, and creating reports for various nonprofits. Whether it was a document that I was sharing with others, or if someone else was sharing something with me, it was important for me to understand what others were trying to say, and to communicate my own thoughts clearly. This clarity is just as valuable in the tech industry.
Whether you are working on a group or solo project, it is in everyone’s best interest that the questions, “what is happening in this file?” or “what is happening in this project directory?” should not take long for a “reader” to understand. Accessible and quickly understandable code creates a more fluid and more effective work environment.
Best Practices for Inline Documentation
What is inline documentation?
Inline documentation, also referred to as “inline-comments” or “comments,” can be defined as text written in the programmer’s spoken language, i.e. English, and can be found throughout source code in a code file. Comments help explain what source code is doing.
What is source code? Source code is text written in any computer programming language, i.e. javascript. A program called a “compiler” translates source code into machine language, a language that a computer can actually understand and, so, execute what it is being told to do. If you are curious to learn more about machine language and the basics of computer science, this free course lecture offered by Harvard University is a great resource: https://cs50.harvard.edu/x/2020/weeks/0/.
Provided below are examples of what single-line and multi-line comments in a javascript code file can look like! Different computer languages use different syntax for their comments. The term “syntax” refers to how you format your comments. Please also note the different syntax for single-line and multi-line comments in javascript below.
Single-line Comments
The comment here follows “//”.
Multi-line Comments
Multi-line comments, also known as “block comments,” may vary slightly in syntax. You may also see a multi-line comment simply wrapped in a starting /* and a closing */.
Source: https://www.digitalocean.com/community/tutorials/how-to-write-comments-in-javascript#block-comments
When should inline documentation be used?
It is important to note that sometimes source code can speak for itself and that comments will not be useful in clarifying your code to others. However, if your source code does not clearly exhibit what is happening in the code, you should then use inline documentation. Comments can also be used to:
- Identify/explain a section of source code that may need to be reevaluated
- Describe at the top of a code file what is happening in that particular file
- Label sections of your code file
What does good inline documentation look like?
Google Developers’ Technical Writing Course on “Writing code comments” summarizes that good commenting is in an active voice, and is concise, accessible and professional. It should not repeat what your source code is telling you, rather provide a reader with context or supplemental information. You can find this lesson at: https://developers.google.com/tech-writing/two/code-comments. To understand deeper what an active voice vs. passive voice may look like in technical writing, feel free to explore this lesson: https://developers.google.com/tech-writing/one/active-voice.
Best Practices for READMEs
What is a README?
A README is a text file in a project directory that describes the project. A README may contain:
- A short description of what the project does
- A short description of what technologies were used
- Links to your code on gitHub and/or your deployed link
- Instructions on how to run the code
- Instructions on how to run tests
- Information on known bugs and/or bug fixes
- Information on the status of the project if it is still in development, i.e. when it is expected to be complete and/or any planned changes to the project.
What a developer chooses to include in a README depends on the nature of the project and is based on what information a developer thinks is important for the audience to understand.
Below is an example of a README from Never Before Homes, a project I worked on during my time at Fullstack Academy’s Grace Hopper Program:
README.md
Why is it important?
When someone opens up your project directory, the first file they will probably look for and read is your README. The README is where information about the project lives, and a useful starting point to understanding how your code works and what it is doing. The better your README is, in regards to its readability, presentation, and content, the easier and better experience someone trying to understand your project/source code will have!
What makes a good README?
A good README is well thought out and well organized! It clearly provides content useful for your audience, perhaps divided into clearly labeled sections. The big picture information about your project can be presented first, and then the more specific content afterward.
In the README example provided, the README is divided into four sections:
1) Never Before Homes (Introduction)
2) Technologies
3) To view the project
4) Instructions on how to download and run project
Furthermore, you may decide to use bulleted or numbered lists in your README.
Good questions to think about when outlining your README include: Who is your audience? What do they need to know?
Conclusion:
In this article I explore what makes good inline documentation and a good README file, and how these written accompaniments to source code are useful to your audience. And, this is only the beginning! There are many other ways you can make your code clearer and more accessible to others whether they are other developers, project enthusiasts, or yourself in the future!
Some topics to look more into include project directory structure and file naming. The Broad Institute of MIT and Harvard has a great resource on directory structure and file naming: https://mitcommlab.mit.edu/broad/commkit/file-structure/. When it comes to source code, helpful things to think about are naming conventions, i.e. for variables, functions, classes, as well as, source code formatting. The Research Computing University of Colorado Boulder’s resource on Coding best practices is a good place to start to learn more about these: https://curc.readthedocs.io/en/latest/programming/coding-best-practices.html.
