# 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.
People frequently write business code like this:
# Setup the main data doSomeProcessWithData(data)
# Do the other process doTheNextProcess(data)
# 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).