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 microsoft/kiota#4796 (comment) 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 😂