Documentation for variables - what form should it be?

[FWExplorer]

Hi,

This is more of a brainstorming question, rather than anything technical. I'd like to stop using my variant of hungarian notation, because it doesn't really look presentable, and it doesn't fit in with standard modern practice.

The way I write variables is like

Account_Number_n
Customer_Name_edt (Customer Name Edit box)
Customer_Name_s
IsNative_b
IsSenior_b
Transactions_n
nth_Transaction_n (This is used as a counter variable inside a loop)
nth_Transaction_Desc_s


I'd like to settle on a more standard style, but still wish to leave behind a reference telling a future developer what type of variable it is, with an arbitrary level of detail as needed.

Let's say the name of the module is calendar.prg.

Should I write a doc called calendar_vars.txt or calendar_vars.ini that is structured to reveal the type of variable, what function it's contained in, the scope, and some comments?
Or should I put it in a dbf table, like Calendar_vars.dbf, with fields like VARTYPE, SOURCEFIL, PROCNAME, SCOPE, DESC?

Or should this be approached differently? If you wanted to document your variables, so that a future developer (including yourself) would understand its purpose - but you DIDN'T want to mess up the variable name, and you didn't want to rely on short comments in your source file, how would you approach it?

I'd prefer not to depend on the standard method of documenting the variable inside the source, because that can get messy, as well. I'd like to include the docs in a separate document that's associated with the source file.

[AngelSalom]

Hi, please take a look at https://github.com/TiendaNube/php-programming-best-practices#variables
Clean Code (https://medium.com/mindorks/how-to-write-clean-code-lessons-learnt-from-the-clean-code-robert-c-martin-9ffc7aef870c) and SOLID (https://en.wikipedia.org/wiki/SOLID) are highly recommended concepts for every application

[FWExplorer]

Angel,

Thanks but I'm not interested in cleaner code. That's a separate subject. I'm just trying to get some inspiration about some creative ways to document variables, specifically in Harbour/Fivewin.

Also, I have absolutely no interest in Object Oriented Programming https://en.wikipedia.org/wiki/SOLID , or anything that the experts have to say about it. I use it only when necessary.

Hi, please take a look at https://github.com/TiendaNube/php-programming-best-practices#variables
Clean Code (https://medium.com/mindorks/how-to-write-clean-code-lessons-learnt-from-the-clean-code-robert-c-martin-9ffc7aef870c) and SOLID (https://en.wikipedia.org/wiki/SOLID) are highly recommended concepts for every application

[Otto]

Angel,

For this reason, I started a program editor project. I save the source code in dbf files. There are fields for comments, status, and links. But developing a comfortable editor is too much of a job, and I've put the project on hold.

Now I organize my projects with HARBOURINO.
Syntax sample for comments: |-
|- for comments in "include files" - not shown in the "patched" release file.

The more I work with Harbourino style, the more I think it is also useful for Fivewin programming.

I mean an extra preprocessor and splitting up complexity for "normal" - John Doe programmers is very potential. For example, for a test, I split up classes and have for every method an own file. This way, you can achieve NASA programming rules: Restrict functions to a single printed page.
Best regards,
Otto

[TimStone]

In earlier days, I put in an extended comment section at the top of each .prg file. In it I listed Functions, Commands, Classes, Methods, and Variables. I would define each one.
/*
SOURCE. abc.prg
USES DBFs. account.dbf, client.dbf
CLASSES

FUNCTIONS

COMMANDS

VARIABLES

*/

Using Classes, however, put your variables as DATA and // comment them.

I've gotten a bit relaxed on this now, and I turned to OneNote. I created a Notebook for the program where everything is detailed ( in theory ... needs updating ).

[FWExplorer]

Oh, hi Tim,

Yes, this is a possibility, as well. Sort of a Table of Contents of the program, or maybe more like an index.

In earlier days, I put in an extended comment section at the top of each .prg file. In it I listed Functions, Commands, Classes, Methods, and Variables. I would define each one.
/*
SOURCE. abc.prg
USES DBFs. account.dbf, client.dbf
CLASSES

FUNCTIONS

COMMANDS

VARIABLES

*/

Using Classes, however, put your variables as DATA and // comment them.

I've gotten a bit relaxed on this now, and I turned to OneNote. I created a Notebook for the program where everything is detailed ( in theory ... needs updating ).

[TimStone]

Each of my .prg files ( and there are many in the application ) has a name that references what they do. So, mCustomer has a customer class, sub=classes, and functions that all relate to handling customers. If I ever have a problem related to the customer information, I know to go to that one file.

The top of the file ( should ) contain the information I mentioned in my earlier post in this thread. Thus, by opening that file, I can see everything I use to track customer information, including the operations ( classes and functions ) data, and variables that are passed. This makes tracking the program so much easier.

Tim

[FWExplorer]

Sounds good, Tim.

But I'd want the notes, including a block for descriptions of each element, to be in a format that a program could easily extract.

In other words, the purpose of the documentation isn't just readibility for human beings, but also a reference for automated processes that might analyze software code in the future.

So there would have to be a consistent structure that lists the types of elements - similar to what you have - along with lookups for each element for further detail. I'm not sure if that's feasiible, in the context of a header in the .prg file.

Each of my .prg files ( and there are many in the application ) has a name that references what they do. So, mCustomer has a customer class, sub=classes, and functions that all relate to handling customers. If I ever have a problem related to the customer information, I know to go to that one file.

The top of the file ( should ) contain the information I mentioned in my earlier post in this thread. Thus, by opening that file, I can see everything I use to track customer information, including the operations ( classes and functions ) data, and variables that are passed. This makes tracking the program so much easier.

Tim

[TimStone]

As Otto suggests, one can create a database to handle all of it. Uniformity in coding would be enabled and a big plus ... but it would take some work.

I would suggest a multi folder approach. On the main menu you could select a section, like Customer, Inventory, Invoices, etc. Then you can have a description showing for that section.

Now, have tabbed dialogs with independent browses. They could be to display DBF's ( with indexes and structures to include descriptors ), Classes, Functions, and Variables. You could dial them in, so if you selected a specific DBF in the browse on the first tab, the others would show the details.

Building it wouldn't be difficult, but getting all the data in there will take a very long time.

Tim

[FWExplorer]

"As Otto suggests, one can create a database to handle all of it."

Yes, that's the type of approach that I'm leaning towards. Some of the older case tools like Dbsee accepted comments for all of the components in its repository, and one could auto-generate documentation from those.

"I would suggest a multi folder approach. On the main menu you could select a section, like Customer, Inventory, Invoices, etc. Then you can have a description showing for that section.

Now, have tabbed dialogs with independent browses. They could be to display DBF's ( with indexes and structures to include descriptors ), Classes, Functions, and Variables. You could dial them in, so if you selected a specific DBF in the browse on the first tab, the others would show the details."

Not sure I want to go that far, but will reflect on it before settling on a solution.

Ok, thanks for your suggestions & inspiration Tim/Otto/Angel.

As Otto suggests, one can create a database to handle all of it. Uniformity in coding would be enabled and a big plus ... but it would take some work.

I would suggest a multi folder approach. On the main menu you could select a section, like Customer, Inventory, Invoices, etc. Then you can have a description showing for that section.

Now, have tabbed dialogs with independent browses. They could be to display DBF's ( with indexes and structures to include descriptors ), Classes, Functions, and Variables. You could dial them in, so if you selected a specific DBF in the browse on the first tab, the others would show the details.

Building it wouldn't be difficult, but getting all the data in there will take a very long time.

Tim