conceptual documentation: readability of the code

[baywet]

We should make a clear statement in the documentation on whether the code kiota generates is meant to be readable by humans or not. And the general philosophy behind it.

@maisarissi to make a decision on the topic before we make changes either way.

[sebastienlevert]

I provided my thoughts on the original issue https://github.com/microsoft/kiota/issues/4796#issuecomment-2180743708 but I'll quote it also.

Regarding the topic of readability. While we will always try to make it as readable as possible, there will always be cases where machine-generated code will need to take a path that impacts the readability of the code in favor of better generation. There are areas where the code is pretty much very readable, where it's a bit less because of the constraints. I don't think we should be peeking into the generated code and we should leave it as is. I see this code to be as opaque as can be while offering really easy debugging and learning experience.

So my stance: We should not tax any of our development efforts to make the code "more readable" at the expense of complex solutions.

[baywet]

This is the docs page... go put a PR together now :D

[sebastienlevert]

Thanks for pushing @baywet... Thanks for pushing 😂