The Importance of Documenting your Code

Hi kids!

let’s talk about ….. documenting how to run a project!! I know, I know. It’s the WORST!! However, every single developer coming behind you to maintain things will appreciate you! Don’t lock up the code so it’s impossible for others to test without some serious deep diving into the code. It’s just rude. You know how to run it and sharing knowledge is a good thing! This industry does not appreciate those who hoard information… that’s why we have blogs and sites like Stackoverflow

Some basic “please do this” steps:

1. If the solution needs a specific project or projects to run at start, note that

2. If there are multiple environment, document how to run locally in each environment. If you need specific config values, note them

3. If user secrets are needed, note that

4. If you need special permissions to handle security requests, note it

5. If the solution can be connected to using integrations, note it

6. If a file structure needs created on a local C drive, note it or check for the folder in the code. If it doesn’t exist, create it for them!

7. Of your company doesn’t have a documentation “space”, add all documentation to the Readme file

8. If the code has standards, note the standards

9. If there are values stored in a deployment tool instead of the code, give instruction on how to use it and how to add additional values

10. If your solution is in a collection of solutions, note those other solutions and if they all need to run at the same time

11. If unit tests need specific data, note it

12. If your database connections are stored elsewhere, make sure connections needed for local testing is noted

13. Note the company URL for all environments - dev, test, UAT, Prod

14. Lastly - don't overdo it. Only document when needed, like the code doesn't tell you already .... DRY (Don't Repeat Yourself)

These are the minimums for every single solution. You can absolutely add more if it’s needed, include screenshots, be specific. In this case, it is always better to have more information than less especially if you decide to leave the company. It is unprofessional to write untestable code and then dump it on someone who has to take days, weeks to untangle and figure out how to locally run and test something that simple instructions will negate.

Be a team player!

Love you, Liv 💜