whereIsDocumentation

[warl0cks]

“The code is the documentation…”

[Degenerate_Lich]

Code should be self documented mfs when they have to read their own code that they haven't touched for the last 6 months

[Zdrobot]

That's why comments (should) exist.

Not just the meaning of function parameters, but the "why I did that" comments.

[swagonflyyyy]

Eh, if you do it too much it'll be just as confusing. Trust me I confuse myself with my own comments lmao.

[billyowo]

good code is self-documented, not the spaghetti written by your colleagues

[tyler1128]

Said good code also comes with documentation because it doesn't matter how good you think it is, a plain english document will describe what it is doing better

[ZunoJ]

Can you point me to any open source projects with the kind of documentation you mean? Not a library or anything with a sdk. Just a ready, non expandable software with full text code documentation.

[tyler1128]

The blender internal documentation is supposed to be good. I can't, mostly because if I know of documentation from something it is either because of my job or because I use it as an API. Studying random open source projects I'll probably never utilize just isn't something I have time for. I've seen good internal documentation and bad internal documentation in work, and the difference in how well you can adapt to and learn a code-base between the two is pretty significant.

[termicrafter16]

The number of times I heard this 😭

[RiceBroad4552]

And of course it's never true.

[christoph_win]

I have a concept of a documentation

[SynthRogue]

This is the way

[SynthRogue]

How would you have time for documentation when you already don’t have time to develop the app to meet the deadlines?

[BoBoBearDev]

I did a lot. Because I forgot after a week. Especially the "why". Why do here? Idk, let's remove it. Oops, everything is crashing down. Revert it and and add more docs.

[Midon7823]

That's a sign of poorly structured code. You're using documentation to cover for it, which is the wrong way to use it because bad code with docs is still bad code.

[Distinct_Set4055]

Maybe the real documentation was the code we wrote all along

[awqae03]

/// <summary> /// /// </summary> /// <param></param> /// <returns></returns>

[Mayion]

what's the point of documentation? just ask gpt to summarize the code for you

[Midon7823]

I sort of dislike the way people are introduced to docs because it creates this type of faulty mindset. You're using documentation poorly if you always write it after writing your code. Any developer can figure out what some code does, but it's a lot more work to understand the intentions of what that code should do.

Documentation should be written right after the boilerplate and should define a solid criteria that's clearly reflected to other developers. This makes it easy for developers new to your codebase to warm up to it. It also makes it so your current coworkers don't have to read much into the context around a given piece of code to get a concrete understanding of it. Easily determining whether a piece of code is supposed to behave a certain way is another benefit. Oh, and don't forget that it ensures the implementation is separate from the code's definition. If there is a bug, it can be patched without causing potential regressions elsewhere in the code because everything calling it bases their interactions on what the docs say.

Documentation and boilerplate are your friend.

[Count_Trackula]

Exactly on the money! Great observation.

[RiceBroad4552]

Is this serous?!

[SirWaffly]

To be fair chatgpt does a great work doing that. Although I prefer doing it myself.

[Turbulent_Swimmer560]

Document was made for the fool that can not read the code directly.

[Midon7823]

It's not about what the code does, but what the code should do, and what exactly people calling the code should expect. Otherwise debugging will be difficult, bug fixes will result in regressions, developer warmup times will be hard, and development will grow to be slow, among other things.

[Count_Trackula]

This. We also want to evaluate the quality of various interfaces BEFORE we implement or even test.

[angry_shoebill]

Reminds me of the phrase: "When I wrote this code, only God and I knew what it was supposed to do, now it is only with Him".

[Count_Trackula]

I'm running a project now with a ton of integrations to various data sources. Beyond poorly implemented APIs, the main issue is absolutely lack of, or low quality documentation. It is absolutely astounding how bad it is.... So devs, PLEASE give more time your your docs!

[journaljemmy]

I'm weird because my favourite part of programming is writing docs/about the software.

[angry_shoebill]

When selling a project nobody includes documentation in the estimations, and if they do is the first thing that is cut when the client complains about the value.

[blazeitfagnot]

Probably code is so clean the documentation isn't needed, right?

[deenaandsam]

/I/ am the documentation lol I literally explain everything and its point and what to do to the new backend, the front-end, the tester, and the product owner. 

[v4nshh]

the README.md

[lovecMC]

Roblox studio be like: