
Don’t document your code. Code your documentation - kawera
https://dev.to/raddikx/dont-document-your-code-code-your-documentation
======
mannykannot
Before arguing this question again, we should have an understanding of what
information a programmer needs to know about a function in an unfamiliar code
base. Depending on circumstances, that may include issues like whether it
modifies its arguments, preconditions/assumptions and post-conditions, failure
modes and error handling, corner cases, resource use, thread safety, time and
memory complexity, the architectural conventions that the function needs to
observe and imposes on other parts of the code, and why this and not something
else. I cannot see the proposition that you can write optimally readable code
simply through the choice of identifiers as being anything but based on a
misunderstanding of just how much information there is in code.

------
damagednoob
In my career I've switched between the two extremes. What I've settled on is
only documenting non-obvious or counter-intuitive pieces of code. Using tools
like javadoc or rdoc are a waste of time unless its API documentation used by
an external team. If the parameter to a method is called Person I don't need
to write it out again.

------
z3t4
paradoxically _less_ abstractions (puttung stuff into methods) can also make
it easier to see what the code does.

~~~
mannykannot
Only to a certain, small level of complexity (or simply just size). Beyond
that you are better off with documented abstractions.

