Re:On Comments in Code
by pydry on Wednesday June 16, 2021 @03:48AM
(#27525979)
I find the exceptions usually boil down to:
* It's not your code - I was working with some UNIX TTY code recently and the APIs are horrendous 1970s throwbacks. But they're not changing. Working with crappy APIs is where comments about the "what" shine the most. You can only go so far with abstraction/encapsulation/facades.
* You don't have time - there's an urgent bugfix you need to get out yesterday. Do you A) rewrite the architecture to make it perfectly understandable and tell the users to wait B) drop a comment in explaining what's going on.
* It's not your code - I was working with some UNIX TTY code recently and the APIs are horrendous 1970s throwbacks. But they're not changing. Working with crappy APIs is where comments about the "what" shine the most. You can only go so far with abstraction/encapsulation/facades.
* You don't have time - there's an urgent bugfix you need to get out yesterday. Do you A) rewrite the architecture to make it perfectly understandable and tell the users to wait B) drop a comment in explaining what's going on.