Terminology Clarification requested

[Thomas Bullock]

Hi John,

Thanks for your comments.  Data structure is a good term, because it allows you to focus from a programming standpoint on just parts of what I have described as a transaction.

Please see below.

> -----Original Message-----
> From: John Ralls [mailto:jralls at ceridwen.fremont.ca.us]
> Sent: Thursday, December 09, 2010 4:37 PM
> To: Thomas Bullock
> Cc: gnucash-devel at gnucash.org
> Subject: Re: Terminology Clarification requested
> 
> 
> On Dec 9, 2010, at 1:10 PM, Thomas Bullock wrote:
> 
> > Hi,
> >
> > Using this excerpt as a context:
> >
> > Message: 1
> > Date: Tue, 7 Dec 2010 09:33:58 -0800
> > From: John Ralls <jralls at ceridwen.us>
> > Subject: Re: close books
> > To: Derek Atkins <warlord at MIT.EDU>
> > Cc: devel gnucash <gnucash-devel at gnucash.org>
> > Message-ID: <2B1F2747-854C-430C-8AAA-05637E30AB51 at ceridwen.us>
> > Content-Type: text/plain; charset=us-ascii
> >
> >
> > [...]
> >
> > A KVP *is* better, but because it's better architecture: The
> closing-entry mark would apply only to one transaction per year, would
> only be important to one split in that transaction (the income/expense
> split; one wouldn't want to hide the split from equity reports), and
> wouldn't have any applicability to any transactions which don't touch
> income or expense accounts. Something of such limited scope doesn't
> deserve a column.
> >
> > Note that the KVP should be on the split, not the transaction,
> because many income/expense reports don't need to look at the whole
> transaction, they just need to total up the credits and debits shown
> in the splits occurring between two dates.
> >
> > Regards,
> > John Ralls
> >
> >
> >
> > Let me ask your help as I work my way to a new understanding of the
> term "transaction".
> >
> > My formation long ago as a young accountant contained this
> understanding of a transaction: it was the accounting expression of an
> activity that happened in the physical world, which the accounting
> ledgers were tracking in their own notation.  For example, suppose the
> activity is buying a car using cash and debt on 11/10/2010.  The
> accounting transaction is that act of purchase.  The accounting
> notation was the language of debits and credits with accompanying
> names describing the purpose of the monetary "buckets" or value
> holders.
> >
> > Thus, in a journal, the transaction would be recorded similarly to
> this:
> > 								    Debit
> Credit
> > 	11/10/2010		New car                     15,000
> > 	11/10/2010		New car loan
> 	10,000
> > 	11/10/2010		Cash in bank
> 5,000
> >
> > Above John says "...the KVP should be on the split, not the
> transaction,..." but in a later follow-up
> > Derek says that the KVP should be on the transaction and not on the
> split, noting further that the date is resident in the transaction and
> not the split.
> >
> > Which of the above in GC terminology is the "transaction" and which
> the "split"?  What makes one of the parts of the above the
> "transaction" and the others the splits?  Can any one of the 3 parts
> be named the transaction be different people?  What keeps the
> transaction from being arbitrarily identified?
> >
> > In my mind all three parts are splits and there is no transaction
> unless all three are there with debits and credits in balance. If one
> or two parts are missing, the transaction is said to be incomplete or
> broken, because it would not balance.
> >
> > Clearly, GC has a different sense of naming these elements and it is
> important to include in basic documentation a clear discussion of the
> terminology as used in the GC world and as used in the Accounting
> world.  I am not interested particularly in changing GC usage.  I am
> interested in understanding clearly how developers see things and why
> things are perceived that way.  Once I see that perspective, then the
> documentation as presently written will become clearer, at least to
> this accountant, and I expect others in the Users' List.
> >
> > Thanks to all who can help me with this.
> >
> 
> Tom,
> 
> Sorry, Derek and I were in programmer mode in that exchange, not
> accountant mode. 

That makes sense.  My interest is understanding clearly the concepts used in programmer mode because a good portion of the documentation reflects that perspective in its use of terminology that accountants are used to using in a different manner.

We were talking about two data structures in the
> program, which are mostly equivalent to the accounting terminology.

Yes, I understood exactly that you were talking as programmers but had not incorporated the "data structure" concept.

> 
> So we have a data structure called a "transaction" that includes a
> variable number (but at least 2) of subordinate data structures called
> "split", along with some date fields, and some "key-value" or KVP
> data. 

I infer then that it does not matter which element of the transaction gets labeled 'transaction' with all the parts that it has in the code.  You are saying that whichever piece of the 'transaction' (as an accountant understands it) becomes the 'transaction' (as a programmer understands it) it is treated as the prime element of the activity being recorded.  It is prime because it has different coding treatment compared to the subordinate parts which have a programming status/treatment that identifies them as subordinate. 

If this description is basically correct, then is there anything that GC coding uses to identify the 'prime element' and by default relegate the remaining elements to subordinate status as 'split' elements for split programming treatment?  What makes one element standout that it is or should be the element that is accorded 'transaction' programming treatment?  Is it strictly an accident of user perception, that is, whatever the GC user types in first?

Each split contains an account, an amount, and some more KVP
> data. The splits are required to balance, otherwise the transaction is
> marked as unbalanced and displayed with a little gray ☒ in the amount
> fields.

Yes, of course, that has to be the case.

> 
> The exchange was about in which data structure it makes more sense to
> attach a KVP "flag" indicating that it's a closing transaction (i.e, a
> transaction moving a summary amount from an income or expense account
> to an equity account).

I do understand this has programming consequences inside GC code and in the broader context of what happens in the case of the 'close books' function.  The details of the process are outside the accounting area of concern.  Accounting just expects all the parts of the transaction to be present and in balance, no matter how that occurs to make the 'in balance' condition a fact.

> 
> Regards,
> John Ralls

If my inferences above are correct, they are important to a proper conceptual understanding in the documentation to help a new GC user.  There has to be some awareness in the documentation that the accounting and programming uses of 'transaction' are different and where the difference lies.

I hope you won't mind correcting me if I have made incomplete or incorrect inferences.

Thanks.

Tom