Learn how to document your code
In our latest resource, we show you how to create a website and use it to document your coding projects.
Why document your code?
Search the web with the right key words for your programming conundrum, and you’re bound to find someone who has written software to address a question that’s at least similar to yours. And not only that, they’re also making their software freely available under an open source license, and writing documentation to help you use their code. How awesome is that?!
Many people who write code are eager to share their programs and allow others to use and remix them according to their own needs. This is why the open source community is so inviting for makers, especially those who want to make projects that are yet beyond their ability to build from scratch.
So unless you plan on turning your code into a money-making commodity, you’re writing scripts that you can share with others. By adding clear, supporting online documentation to your code, you’ll help people all over the world to not only use your software but to also understand what everything does and become better programmers themselves.
In our latest resource, we show you how to use docstrings to automatically create documentation for your Python code. Then, we walk you through using Sphinx to build a website showcasing this documentation and any example scripts you want to share with the world.
You’ll learn how to create supporting documentation to guide users through elements of your code, add multiple pages to your website, and use themes to customise the site’s layout and make it stand out.
You can find the resource here, and our full list of free resources here on our projects site.
More free resources
We’ve also recently released a new Sense HAT music player project, along with a resource teaching basic Raspberry Pi terminal navigation skills with a fun game to find all the Pac-Man ghosts.
Document your programs ? Why do you think we call it ‘code’ ? <- typical response from fools.
As my old boss used to point out “if it isn’t documented it doesn’t exist. If it doesn’t exist what did we pay you for?”
Raspberry Pi Staff Martin O’Hanlon
“if I dont know how it works, what use is it to me”?
I can relate to that.
Not only that, but your own memory fades with time.*You* need your own reminders of what, how and why.
Raspberry Pi Staff Martin O’Hanlon
I am one of the most frequent readers of my own documentation.
I often include instructions in my own projects about how to do ‘usual’ tasks like setting it up for development or deploying, because I know if I dont do it for 3 months I will have forgotten how! + it helps others who want to get involved.
“How awesome it that?”
maybe should be
“How awesome is that?”
Writing documentation for programs should better prepare students for success in many different technical areas. For example, the reason some students with good marks in low-level mathematics struggle when asked to write proofs is lack of technical writing skills. Thus, developing better writing skills could end up being as useful as the programming.
I’ve said this time and again to trainees in my particular field: It’s not finding the answer that’s the problem, it’s finding the answer again.
I currently work with a code base where the mantra is “The source code is the documentation” – and every time I attempt to find out something I might as well punch myself in the face for all the good the code base is to me.
When you think about how some programs do a lot of computations, documenting the code will save you the hours or days it could take to make sense of the formulas you wrote!
Great lesson to be learned and one of the biggest failures of enthusiast and hobbyist programmers. Documenting code is often what separates a professional from an amateur – it doesn’t matter how good your code is if you can’t hand it over for another developer to easily understand.
Comments are closed