Hi everyone! I'm a 23-year-old female just getting into documenting my work. I've already completed some HTML and CSS projects without keeping any documentation, but I really want to start making it a habit moving forward. Right now, I'm a bit lost on how to document effectively. I feel like the code itself should explain what it does, but I want to include a README. I've been using comments mainly as reminders for myself about each section. Could anyone share specific examples or tips for beginners who are looking to write documentation or README files?
5 Answers
Lastly, try to focus on tracking the lessons you've learned as you go along. At the end of your project, write a brief on what went well and what you struggled with. This not only helps you improve later but also gives you a solid reference point for next time! Trust me, it’s invaluable when you’re picking up a project after a break.
When I was coding, I would organize my code into smaller sections and name each function descriptively. It helped me keep my main program easy to read—like a story! If your language doesn't allow long function names, combine a comment with the function call. This way, you can still maintain readability without losing context.
In terms of README files, after finishing a project, update it with key points like your concept, features, and components. Explain how to use your application or the main functions involved. This isn't just for others—it's to remind your future self what you did and why. Making clear documentation can really help in interviews when they're asking about your past work, so it's always good practice!
When it comes to comments in your code, think of them as explaining the 'why' behind your choices rather than just stating what the code does. For example, if you have a tricky workaround, a note like `// this is a workaround for $remote_bug: ` can be really helpful. It's also good to remind yourself that documentation becomes more crucial as your projects grow larger and more complex. You don’t need it for every little thing while you're learning, but developing the habit now will pay off later!
For personal projects, I find it helpful to keep a text file where I jot down everything as I work. Start with your concept, aims, and a rough plan. You can even have a working journal to track what you've done each day. This way, when you revisit the project, you know exactly what your goals were and how you got there. It transforms your code into a story that you can easily follow later!
Totally agree! Plus, when you look back at your code months later, those comments can save you so much time trying to remember your thought process.