On 9/27/2013 11:54 AM, Cyndi Bradberry wrote:
Can anyone point me to a best practices for documenting code changes ? This would have to cover RPG IV and Free and CL programs. We are working towards a SOC 2 Type 1 compliance.
I deeply wish I had the money to buy a source control system.
Or the buy-in from my colleagues to use an open source SCM like Git,
Subversion or even CVS.
In my opinion, the key advantage is the freedom an SCM gives one to
experiment, to make changes freely, knowing one can roll them all back
simply. When people think about commenting out obsolete code, that
might have been good enough in the 1980s, when a typical application
consisted of a program to load a scratch file, FMTDTA to sort/select
records and a print program to print them out. Making a change to this
system was very straightforward. Two programs. The magnitude of the
change was always small and easy to deal with.
Today, an application spans dozens of programs and files. Making even a
simple change can affect a dozen objects. When you have to manually do
a pile of work to revert those changes, you don't make changes without a
ton of deliberation and testing. It takes a long time to get to the
point where I want to show the users the effects of their request, and I
very, very rarely give them more than one choice because making changes
(and reverting them) is too darned hard.
With an SCM in place, I could try option 1, test it, give them pretty
quick feedback and simultaneously try option 2 and 3 and give them
choices. When they decide they like option 3, I'd promote that one and
off we'd go - much faster from concept to completed.
My job is to change things. Anything that adds to my ability to make
quick changes is a Very Good Thing.
I find this a separate discussion from capturing the narrative of 'how
did we get here?' Having a block of commented out code sort of gives me
a narrative, but it is an incomplete narrative until I have read ALL of
the commented out code in ALL of the affected source code. And then
what about configuration changes, things like 'Added jt400.jar to /jar
folder and edited environment variable CLASSPATH to add it system wide'?
What source member am I going to put that into? A centralised library
of decisions, changes and so on seems a better idea to me. Let an SCM
keep track of 'what changed' and write a plain language document
explaining 'why did this change?'
--buck
midrange.com
