DEV Community

Talk : How often do you document your code ?

Lotfi Jebali on May 22, 2024

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 !!

Collapse
 
deadreyo profile image
Ahmed Atwa • Edited

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.

Collapse
 
lotfijb profile image
Lotfi Jebali

Is that good for the experience of your fellow workers ? especially beginners

Collapse
 
mistval profile image
Randall

I write a fair amount of comments (and I think the "self-documenting code" concept is BS).

I also put a docs folder 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.

Collapse
 
lotfijb profile image
Lotfi Jebali

I love how you approach things

Collapse
 
pengeszikra profile image
Peter Vivo

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:

  • type definition
  • example usecase if some busines logic are need explanation.

I also use README.md for a core and develop knowledge. If necessary write additional topic in markdown under /docs

Collapse
 
lotfijb profile image
Lotfi Jebali

Would definitely love if there was a langDoc for every language not only js

Collapse
 
prsaya profile image
Prasad Saya

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.

Collapse
 
lotfijb profile image
Lotfi Jebali

I totally agree, sometimes writing the flow with pseudo code prior to coding helps a lot

Collapse
 
codewithchema profile image
Chema
  1. 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.

  2. 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.

  3. 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.

Collapse
 
lotfijb profile image
Lotfi Jebali

Feels like you make junior devs life easier ! keep it up and great job

Collapse
 
lotfijb profile image
Lotfi Jebali

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

Collapse
 
orsini13 profile image
Udeh Udochukwu

I just comment, and in commenting, I prefer to state why not what. I can do bboth as well

Collapse
 
lotfijb profile image
Lotfi Jebali

Great point

Collapse
 
orsini13 profile image
Udeh Udochukwu

Thank you Lofti

Collapse
 
phalkmin profile image
Paulo Henrique

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

Collapse
 
lotfijb profile image
Lotfi Jebali

I should definitely try it!

Collapse
 
andreas_stesinou profile image
Andreas Stesinou

Let's speak it an opposite way. How often do I code my documentation?

Collapse
 
lotfijb profile image
Lotfi Jebali

How is that

Collapse
 
lotfijb profile image
Lotfi Jebali
Collapse
 
jhelberg_63 profile image
Joost

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.

Collapse
 
altesack profile image
Marat Latypov • Edited

Just in my opinion:

  1. Application logic should be documented. User interface, or API for external usage should be documented.

  2. The code should be clean enough, so there should be no need of any documentation
    The code should be clear and unambiguous documentation itself.

Collapse
 
andre_orlowski_b2d1a3d47e profile image
Andre Orlowski

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.

Some comments have been hidden by the post's author - find out more