The other day I had to submit a ReadMe file as part of a school project that I developed iteratively. Meaning it was somewhat large. Instead of writing the readme as I developed, I finished the programming part of the assignment and wrote the readme last. A ReadMe is just a file that explains a project.
In my case, the readme had to explain what the project does, why I chose the approach I did, the questions I had for the professor about some things that were already implemented in the project. It is supposed to make someone else, (another developer) understand my work.
How did I manage to write a detailed enough readme file at the end of development?
Comments!!
Throughout my entire code, I keep adding comments explaining my logic and thought process. Mainly for my own good because most of the time I don’t remember why I did something. Some happen to be unnecessary but frankly, I don’t care because I realized how important they can be. When I was writing the readme file, I was able to give a step by step detail on my thinking process and reasons I did things the way I did no problem. In a way, it was also like revising my work because this was something I had no prior experience building.
I wish I was able to share it, but school policy does not allow us to publish assignments online because of plagiarism
How I use comments:
- Writing at the beginning of a function explaining what the function does
- Inside loops to explain what the loops do and why
- Next to new syntax that I have just started using and why
- Indicating references I used
For this class, I am using comments religiously because it’s in a language I have just started using, C, and it’s low-level programming. It needs much more effort than high-level programming.
Also, I made them as detailed as possible just to make the work of the TA’s (teaching assistants) going through my code easier.
