All engineering is reverse engineering if you document things poorly enough.
@ids1024 My colleague Stefan had the habit of just writing readable code; I kept writing documentation…
Turns out that readable code was much more liked by others…
Readable method names and easily refactorable code are much impactful than documentation!
@riese @polx @ids1024 I always try to keep the code and tests readable. Documentation (in the code) is added when it's helpful for the reader to understand _why_ something is done like it is done. An example would be, skipping (obsolete) bytes in a custom binary format. Then the documentation explains why they became obsolete and are now skipped.
@lamitpObuS @polx @ids1024 ah. yes. good point.
During refactoring it's sometimes necessary to point out the whys.
However, no comment is often better than a wrong comment.
I have to admit to the bad habit of now and then adding a "why" comment, then redesigning the whole block and forgetting to erase the then-wrong comment. Which is always slightly embarrassing in the reviews ^^
@riese @polx @ids1024 Your code/pull-request reviewers should be able to spot them for you.
But no one is perfect. We all iterate to get closer. 😉