My one principle for logging is that if you think your code needs a comment to explain it, you probably actually need to be putting whatever you're writing in a debug logging statement.
It's easy to remove that line later. It's a lot harder for ops to figure out what the hell is going on if it's not working.
2019-08-20 14:00:03.270 INFO Implements Ukkonen's suffix tree algorithm. For more on how it works, see https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.10.... or get a PDF from our file share at \\some\path\to\departmental\share\FileThatWasDeletedThreeYearsAgo.pdf
2019-08-20 14:00:03.856 INFO Implements Ukkonen's suffix tree algorithm. For more on how it works, see https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.10.... or get a PDF from our file share at \\some\path\to\departmental\share\FileThatWasDeletedThreeYearsAgo.pdf
2019-08-20 14:00:04.137 INFO Implements Ukkonen's suffix tree algorithm. For more on how it works, see https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.10.... or get a PDF from our file share at \\some\path\to\departmental\share\FileThatWasDeletedThreeYearsAgo.pdf
2019-08-20 14:00:04.523 INFO Implements Ukkonen's suffix tree algorithm. For more on how it works, see https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.10.... or get a PDF from our file share at \\some\path\to\departmental\share\FileThatWasDeletedThreeYearsAgo.pdf
Something tells me that my logging under that heuristic wouldn't fly with sysops.
# Check if thing X due to some requirement
if (some check happens):
# Do the workaround
<some hack which currently works>
# Finish up
dispatchItToZ()
And provided this works, okay, no problem. But the reality is this is going to get deployed, hit some edge case requirements didn't cover, and start failing. Written as this, someone is probably looking at that output wondering where it's failing.
If on the other hand each of those comments was a debug log level line, as they should be, then at minimum the logs now have a mode where they document exactly what happens and why (of course a business process should be logged at Info IMO).
Well, originally it was just a joke. But since we're going there:
Needing to log at quite that level of detail worries me. It implies that non-deterministic behavior is pretty pervasive in the codebase. I'm generally a lot happier when the logging strategy on the happy path looks like:
1. Get all your I/O-type stuff handled before the call stack gets deep.
2. Log your inputs
3. Run the calculation
4. Log your outputs
If what happens in step 3 is deterministic, then it should always be possible to explain the output by looking at the input, and reading the code. And, if you've accomplished that, then it's straightforward to convert the logs into a test case.
It's easy to remove that line later. It's a lot harder for ops to figure out what the hell is going on if it's not working.