3 ms·
I used to argue that well-written code needed no documentation, but I read various articles about documentation anyway. The takeaway was this: Even if my code
by nsmartt 13y ago
I used to argue that well-written code needed no documentation, but I read various articles about documentation anyway.
The takeaway was this: Even if my code is clear, neither I nor anyone else should have to read through a function in order to understand what it does. Reading a comment should be enough to use it.
- mhaymo 13y agoThis has the additional advantage of separating the specification from the implementation. If e.g. a javadoc comment says "@throws IllegalStateException when foo", then I know if I change the method, I have to preserve that behaviour.