Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
I've spent a long-time in open source. The one thing that invariably remains…the source code (and it's git history). All other things rot and decay far faster.
So, include whatever comments can help provide contextual support of the local "state" of the code.
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
In addition, one must consider that placing way finding comments in a code-base are of high value.
There have been a few cases, where past decisions/specs were lost but we still had code. I don't want to go and "backfill" those specs, so I'll write a note saying "This is my understanding given what I've been able to piece together."
Okay, maybe I am viewing it too much from a business perspective. It seems like there are a lot more specs from a non-technical view there. This somehow eliminates the need for specs inside code.
If you use comments as way to communicate with other developers working on the same code base and have no real communication channel outside of that, then I can better understand the necessity!
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
We're both looking at the same "elephant" but from different perspectives. The code is the most accurate representation of the product. It says exactly what the product is. There will invariably be cases where the intention of the code will be hidden in a private Slack channel, a lost email, or even an unrecorded Zoom meeting.
The code is the product and provides the most reliable place to "pin" a way finding comment/annotation.
Recovering interrupter with occasional relapses, lover of spreadsheets, blogger, programmer, adept debugger, conjurer of analogies, and probably other things.
I've spent a long-time in open source. The one thing that invariably remains…the source code (and it's git history). All other things rot and decay far faster.
So, include whatever comments can help provide contextual support of the local "state" of the code.
In addition, one must consider that placing way finding comments in a code-base are of high value.
There have been a few cases, where past decisions/specs were lost but we still had code. I don't want to go and "backfill" those specs, so I'll write a note saying "This is my understanding given what I've been able to piece together."
Okay, maybe I am viewing it too much from a business perspective. It seems like there are a lot more specs from a non-technical view there. This somehow eliminates the need for specs inside code.
If you use comments as way to communicate with other developers working on the same code base and have no real communication channel outside of that, then I can better understand the necessity!
We're both looking at the same "elephant" but from different perspectives. The code is the most accurate representation of the product. It says exactly what the product is. There will invariably be cases where the intention of the code will be hidden in a private Slack channel, a lost email, or even an unrecorded Zoom meeting.
The code is the product and provides the most reliable place to "pin" a way finding comment/annotation.
Specs inside code are…treacherous. A URL in the code to that spec? Gold!