Kai Chevannes

67%
Flag icon
In addition to describing what the code is doing, implementation comments are also useful to explain why.
Kai Chevannes
I'm not convinced that implemnetation comments should ever be describing "what". This suggests to me that we need to apply refactorings to make the code more obvious. Function names are much less likely to become stale than several block comments and as a developer I trust code much more than I trust a comment telling me what some code is supposed to be doing rather than what it is doing. On the other hand, if we doc comment all methods, these refactored methods would have completely useless doc comments. Maybe that means they really shouldn't exist? Maybe these methods then should only be nested in the function? Though in that case maybe it really is simpler to just write "what" comments?
A Philosophy of Software Design
Rate this book
Clear rating
Open Preview