AnsweredAssumed Answered

vrf Does anyone document their programs???

Question asked by jcmartin on Mar 29, 2005
Latest reply on Mar 29, 2005 by jcmartin
  • Comment • 5

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".

No one else has this question

Outcomes