Note : This is a discussion post
How often do you document your code ?
How much will it take you on average ? Do you really devote time to the documentation task ?
Do you document your code in order to make it understandable for someone new to your codebase ?
Thank you!
LET'S TALK !!
I prefer to focus on writing clean, readable and straightforward code that's easy to understand, than to focus on documenting and explaining my code.
This would mean that I would come back and re-iterate over my code to simplify it, instead of writing comments or documenting how it works.
If the code structuring is logical and the implementation is straightforward, it would be much easier for someone else to work on it, than to make a code mess and just document it.
Is that good for the experience of your fellow workers ? especially beginners
I write a fair amount of comments (and I think the "self-documenting code" concept is BS).
I also put a
docsfolder in most of my projects and throw a few markdown docs in there, especially if there's any manual maintenance that ever needs to be done (otherwise I myself will forget how to do it, let alone someone who's new to the project).If I'm going to leave a project or a company, I'll try to take as much time as possible to write/update more docs. Until then, I'd say my documentation is "adequate but could be a lot better". Ultimately, "writing amazing documentation" always loses the prioritization war to "adding new features". Often I feel like I have to sneak in documentation without anyone knowing or they'll ask me why I'm spending my time on it instead of writing more code.
I love how you approach things
I am working on near legacy 7->3 years old code base js-react and tons of library, around 300 LOC package json. No option to change typescrip, but I started using jsDoc which is perfect for two things:
I also use README.md for a core and develop knowledge. If necessary write additional topic in markdown under /docs
Would definitely love if there was a langDoc for every language not only js
I think one should document first and then write code along. This way, you are clear what to do, and then do it (write code). This will evolve as the program develops and changes.
Code comments can be for a module, class, method or a construct. This is just part of implementation documentation.
This could also be non-coding aspects like initial design, requirements or just plain pseudo-code. This is more relevant to complex programs.
I totally agree, sometimes writing the flow with pseudo code prior to coding helps a lot
Varies, I work with a team comprised of junior developers. I try my best to balance how much to document and when to. When I'm building a tool - I typically document fairly often.
A few hours, a day out of a week. We have our blocked off time for R&D, so I sometimes use that time to document.
Yes, I believe it is important to document with intention to teach. Again, I believe it's a balance where I'm not handholding, but I'm also not making large assumptions about what their level of understanding is.
I'm trying to create a friendly and open environment for our team with communication and a way for everyone to learn. So far, it looks like it's been helpful.
A final note on documenting -- I have personally found it helpful, especially when you jump out of a project for something else and come back later. It's refreshing to have notes, and it's given me a clearer understanding of the code I wrote.
Feels like you make junior devs life easier ! keep it up and great job
1) I document my code only if I feel it that the logic is too complicated
2) I don't really devote special time but when I do I try to make it clear and concise, let's say I dont spend more than 40mins to 1hour documenting some stuff I built
3) Yes, I try to make it easier for someone that doesn't know what is my code about
I just comment, and in commenting, I prefer to state why not what. I can do bboth as well
Great point
Thank you Lofti
Now with mintlify every bit of code is well-documented.
Before that it was basically minor comments about how everything worked in that function or file
I should definitely try it!
Let's speak it an opposite way. How often do I code my documentation?
How is that
You don't want to miss this
CodeCompanion is an AI assisted docuemntation tool that will be launching soon!!!
When writing documentation before writing code, the problem solved by the code is better understood. Literate programming allows for documentation with bits and pieces of the code in between. Literate programming is a life saver, not just for me, but also for the person picking up the stuff when maintenance is due and when changes are needed.
Just in my opinion:
Application logic should be documented. User interface, or API for external usage should be documented.
The code should be clean enough, so there should be no need of any documentation
The code should be clear and unambiguous documentation itself.
Besides API documentation I myself only document why code needs to be there and why it does something. The what should be documented through cleanly crafted code.