> It will work or not. In the meanwhile the side effect might not be useful anymore and become a useless call, or it might actually be doing something else that is now a primary effect. Hopefully there will be tests or external checks to validate the functionnality isn't broken.
If I have a Function_A that calls Function_B because it needs something Function_B does...
- If Function_A no longer needs that side effect, then Function_A should be updated to reflect that
- If Function_B no longer implements that side effect, then changing it has broken Function_A (and either B needs to be put back the way it was, or A needs to be updated to not rely on B doing it)
Both of those alternatives result in Function_A needing to be updated if it's no longer relying on Function_B doing the thing it was relying on it for. As such, any comment discussing that reliance can/should be changed when the code is changed.
Is there some other alternative that I'm not thinking of? Can you provide a concrete example, because I'm not following you.
> Comments won't have that level of scrutiny, so accepting that fact and treating them accordingly feels logical to me.
When I go into code, especially code with lots of relationships between them (large parent/child hierarchy, etc), it can be hard to understand what the code is doing. Comments make that understanding faster. They can be a difference of hours pouring through code. Even just a comment at the top of a file indicating what the code/class in the file is for (it's purpose for existing) and what other classes it's directly related to / uses can be a HUGE speed gain. The idea of not bothering to include that information because someone can't be bothered to do a good job keeping it up to date is just... confusing to me.
Function_A needs a connection to some file server, and for system specific reasons it wants it to have no timeout. For that it calls Function_B that is targeted to batch processing boiler plate, but also extends file server time outs. Function_A isn't a batch, but will still rely on Function_B for that side effect, with some comment on that.
One day the org upgrades its infra, and file server connections radically change but they take care of preserving compatibility. But no timeouts anymore, setting them do nothing.
They have the choice to go through the hundreds of instances where Function_B was called, look at the use case, and update it, though dozens of MR throughout the whole organization. Most of it probably on code that doesn't belong to the team making the file server change.
Or they can get rid of the timeout management in Function_B, alert the org of the change and request each team to deal with it on their own terms, and call it a day. Function_A will continue calling Function_B, and perhaps the new system timeouts are irrelevant, or perhaps new optimization options were added, and it happens that Function_B sets the right flags for Function_A to work in the best conditions.
The reasons to call Function_B will have either disappeared or changed, but the code will continue working, and at some point the responsible team might want to update the comments to reflect that, but it won't be a priority.
> understand what the code is doing
To me you're looking for design documents, not code comments.
I feel your pain, while also seeing no real good solution to understanding really fast a complicated and huge project. Comments can sure helps, the same way they can also be deceptive and send new devs into spirals.
I see it as a tradeoff between optimizing for new devs accessibility and pay the price in daily development and maintenance time, or having newcomers spend a lot of time upfront in exchange for more velocity for the existing members.
I personally tend to prefer the latter orgs, and find the code quality to actually be much better. It's usually a sign the org isn't shuffling or pumping new devs here and there every thursday, and people get to spend the time to understand the code base as it actually works, without needing to take too many shortcuts (I wouldn't see asking for an existing member to walk through the code as a shortcut btw)
If I have a Function_A that calls Function_B because it needs something Function_B does...
- If Function_A no longer needs that side effect, then Function_A should be updated to reflect that
- If Function_B no longer implements that side effect, then changing it has broken Function_A (and either B needs to be put back the way it was, or A needs to be updated to not rely on B doing it)
Both of those alternatives result in Function_A needing to be updated if it's no longer relying on Function_B doing the thing it was relying on it for. As such, any comment discussing that reliance can/should be changed when the code is changed.
Is there some other alternative that I'm not thinking of? Can you provide a concrete example, because I'm not following you.
> Comments won't have that level of scrutiny, so accepting that fact and treating them accordingly feels logical to me.
When I go into code, especially code with lots of relationships between them (large parent/child hierarchy, etc), it can be hard to understand what the code is doing. Comments make that understanding faster. They can be a difference of hours pouring through code. Even just a comment at the top of a file indicating what the code/class in the file is for (it's purpose for existing) and what other classes it's directly related to / uses can be a HUGE speed gain. The idea of not bothering to include that information because someone can't be bothered to do a good job keeping it up to date is just... confusing to me.