Add example effective dates to a standard #53
Conversation
Some of the PR's have include discussions about ensuring teams are not penalised because they are having to work with code bases that do not follow whatever is the current latest standard as defined here. We have discussed manually versioning our standards. Concensus however was as we are using source control, manually applying a version seems an unnecessary burden. Another solution has been to use dates. This solution also fits in with one of our current principles for standards > ...all standards must define the period of time that they are effective and how they have changed over time The problem is we don't as yet have an actual example of how to go about this. Hence this proposed change to the Java coding standard, to demonstrate (and collaborate) on an approach that can then be retroactively applied to our existing standards, and used for any new ones in the future.
Cruikshanks
force-pushed
the
example-effective-dates-for-standards
branch
from
2e0f941
to
24c180d
Compare
|
Thank you for this - I was thinking along very similar lines. |
standards/java_coding_standards.md
Outdated
| ## Standard applied | ||
|
|
||
| This standard was first agreed on 10 Feb 2020. | ||
|
|
||
| This standard was last updated on 10 Feb 2020. |
There was a problem hiding this comment.
Yes I'd agree with having something pretty much exactly like this.
I was wondering about:
- having a heading of History or Status rather than Standard applied
- using the word adopted or approved rather than agreed
- for each change, having a quick not on what had been changed
So, something a bit like:
Status
10/02/2020 - This standard was formally adopted on 20 Feb 2020.
17/02/2020 - Updated to include adoption date.
24/02/2020 - Updated to cover other things we hadn't thought of.
24/02/2021 - Completely changed to use Standard X from our new friends at Oracle.
Or something along those lines.
There was a problem hiding this comment.
- Think Status as the heading is a good shout
- Think adopted is a much better term than agreed
- TBH I'm pretty against the idea of a summarised history. Whilst these documents are version-controlled it's a single click to open the history and see both the commit message and the actual changes all with the actual date they were made, and by whom. If you want that detail, its not much effort to drill in and find it. Whereas I think it adds reasonable effort plus more scope for forgetting to add the summary, or getting the info incorrect.
If anyone else sees this, please weigh in with a 👍 or 👎 on what you think.
There was a problem hiding this comment.
I agree with you.
I didn't word it well and my example didn't really convey what I wanted either!
What I'd like to have is some way of including a sort of "major" history in the standard, as and when people felt it was helpful as I think it could be a good idea to signpost people to go and look at the history.
But it definitely isn't required yet so we probably don't need to worry about it for now? (YAGNI)
I'm happy with:
Status
This standard was formally adopted on 20 Feb 2021.
And if we want something in the future then we can do this:
Status history
20/02/2020 - We defined our own internal standard based on industry best practice and our hands-on experience.
20/02/2021 - We decided to ditch that and just use the new standard that Oracle published instead.
But we don't necessarily need to discuss and agree that now.
Great suggestion by @bensagar-ea on how to improve the wording.
|
Having got the initial nod that this was the kind of thing @bensagar-ea was thinking of when we talked about making dates visible I'm opening this up for review! |
|
Looks good. I approve. |
Some of the PR's have include discussions about ensuring teams are not penalised because they are having to work with code bases that do not follow whatever is the current latest standard as defined here.
We have discussed manually versioning our standards. Concensus however was as we are using source control, manually applying a version seems an unnecessary burden. Another solution has been to use dates. This solution also fits in with one of our current principles for standards
The problem is we don't as yet have an actual example of how to go about this. Hence this proposed change to the Java coding standard, to demonstrate (and collaborate) on an approach that can then be retroactively applied to our existing standards, and used for any new ones in the future.