Re:I no longer understand my PhD dissertation
by jimbokun on Sunday February 14, 2016 @09:15PM
(#11101145)
I find one place where comments are absolutely critical is in external facing APIs. Summary of the purpose of the API, purpose of each method, valid arguments and possible return values. Think how often you need to read the comments for whatever libraries and APIs you use in your work.
[ Parent
| on HN ]
Re:I no longer understand my PhD dissertation
by vinceguidry on Sunday February 14, 2016 @09:48PM
(#11101243)
I deal with two types of APIs. Well-documented and otherwise. For well-documented APIs, I can simply re-read the documentation to figure out the other side of my code.
For the rest of it, I try to write as cleanly as possible, and as robustly as possible the first time, so I'm not in the dark the next time I have to look at it. If I have to take time out to re-understand how it works, I'll just take the time and not feel guilty about it. The company wanted me to use that dreck, I'm not going to feel bad about having to take more time with it.
I don't think comments would help much in the second situation given decent engineering the first time around. If it's my code, I'll usually recall the idiocy I had to work around when running down whatever issue had me looking at it again.