3 ms·
Don’t document your code. Code your documentation
- z3t4 10y agoparadoxically less abstractions (puttung stuff into methods) can also make it easier to see what the code does.
- mannykannot 10y agoOnly to a certain, small level of complexity (or simply just size). Beyond that you are better off with documented abstractions.
- damagednoob 10y agoIn 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.
- mannykannot 10y agoBefore 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.