AnsweredAssumed Answered

vrf Does anyone document their programs???

Question asked by jcmartin on Mar 29, 2005
Latest reply on Mar 29, 2005 by jcmartin

As Mike say it is very important to have a kind of VEE Programmer's Manual.
If it is used, the documentation can be reduced. Very quickly, some norms we use are:

- Source code:
     In general using lowercase characters.

- Names of global variables:
     - G_name_global_to_all_source
     - GL_name_global_to_library
     - L_name_local_to_context.

- Name of User Functions and User Objects:
     - UF: F_name_of_the_function (lowercase)
     - UO: NAME_OF_USER_OBJECT  (uppercase)

- We use to copy (if possible) the content of the formula BOX or the VEE object in its name. In such a way, it is possible to minimize all the object and see what they do.

- We use a different colour code for most specific VEE User Objects. Specially we use a specific different colour for:

     - Objects that call User Functions.
     - Objects that call User Objects.
     - Objects that declare global variables.
     - Objects which assign global variables to different values
     - Notepads
     - Objects with interface with the user (displays, selection objects).
     - Objects with ActiveX controls.
     etc.

- If we want to inform about the specific way to code, we use a Notepad (now it is easier with VEE 7.0), in the specific User Function or Object.

- We use to store functions in libraries to be reusable with a common functionality.

best regards,
     



> -----Mensaje original-----
> De: Mike Groves [mailto:mike@grovesnet.org]
> Enviado el: jueves, 17 de marzo de 2005 10:15
> Para: VRF
> Asunto: RE: [vrf] Does anyone document their programs???
>
>
> Maria,
>
> As some have already pointed out, there are many ways to document a
> VEE program, probably because there are many different needs of the
> recipients of these programs. In my case, I generally programmed by
> myself for the production test dept. My main reason for documenting
> a VEE program was so that sometime later I could fire up the source
> code and remember what was going through my head when I laid it out
> the way I did. (Of course, there were also ISO9000 requirements and
> the fact that I knew someday someone would have to follow behind me
> and try to make sense of my work.)
>
> I strongly agree that part of documenting a VEE program is creating
> UserObjects and UserFunctions that are NEAT(!) and orderly. No long
> wires roaming around the screen. No sequence lines joining boxes if
> they are not needed. Keep all UO's and UF's to ONE SCREEN. And many
> other things as well that make up clutter-free code. Trying to read
> VEE code that was well written, versus code that was poorly written
> is like night and day, even though they both may have done the same
> job. I also have a color scheme worked out that allows me to change
> the color of common types of objects for even easier readability.
>
> (Thanks Robert. I agree, the proper naming of your variables, pins,
> and boxes adds a LOT to the readablility of your VEE code.)
>
> I harp on this, because in my early VEE programming days, I had the
> (not so) glorious job of taking another programmer's spaghetti code
> and attempt to figure out what each object did, then clean it up so
> I could remember later exactly what it did and how it did it.
>
> Enough of that. OK, here is what I did to leave myself bread crumbs
> to refresh my mind as to what was happening in spots that were hard
> to follow. In the upper-left corner of every VEE object you'll find
> a "bar". Click on this and select "Description". Here you can leave
> as long or short a description of that object as you wish. In fact,
> in VEE 7 they FINALLY souped up this area and now allow you to have
> different fonts, colors, point sizes, use underlining and strikeout
> bold and/or script. All it's missing is a spell checker! Anyway the
> idea is to document your UO, UF, formula box, whatever, so that YOU
> can easily remember what it did and why it was even there.
>
> Since I didn't care to document every object, I needed a way to see
> that there was help available a couple of clicks away, so I decided
> to add an asterisk to the end of an object or function's name. This
> worked out extremely well and I've been doing it ever since. It was
> literally all the documentation I needed for 95% of the programming
> I did. I kept revision changes documented there, for the boxes that
> were affected. I even stored ideas there for improving that section
> at later time. Finally, I always used the "Description" area of the
> Main screen to keep my top-level documentation for the whole thing.
> It sometimes got quite long, but it had the whole revision history,
> functionality, etc, and (unlike a Notepad box), I was not concerned
> how long it got. And as added benefit, I could never misplace it!
>
> Well, you asked for "details", so I included a lot. (Others here on
> the VRF know I can get long-winded at times.) I sincerely hope this
> helps and wish you the very best.
>
> Mike Groves
>
>
> -----Original Message-----
> From: maria gershman [mailto:mariagershman@gmail.com]
> Sent: Wednesday, March 16, 2005 8:00 PM
> To: VRF
> Subject: [vrf] Does anyone document their programs???
>
>
> Greetings vrf,
>
>
> Can you please describe with details how you document your programs?
>
>
>
> Sincerely,
>
>
> Maria
>
> ---
> You are currently subscribed to vrf as: jcmartin@indra.es
> To subscribe send a blank email to "join-vrf@it.lists.it.agilent.com".
> To unsubscribe send a blank email to
> "leave-vrf@it.lists.it.agilent.com".
> To send messages to this mailing list,  email "vrf@agilent.com". 
> If you need help with the mailing list send a message to
> "owner-vrf@it.lists.it.agilent.com".
>

---
You are currently subscribed to vrf as: rsb@soco.agilent.com
To subscribe send a blank email to "join-vrf@it.lists.it.agilent.com".
To unsubscribe send a blank email to "leave-vrf@it.lists.it.agilent.com".
To send messages to this mailing list,  email "vrf@agilent.com". 
If you need help with the mailing list send a message to "owner-vrf@it.lists.it.agilent.com".

Outcomes