Comments

[Anonymous]

I just wanted to ask the group what styles of comments / level of commenting
they employ. I am a very thorough commenter (which comes of having a very
poor memory) and inclue a function header which describes the function and
line by line comments for all my functions. This helps alot but I end up
spending more time writing / maintaining my comments as I do writing and
maintaining my code. What are the thoughts of the group? I have included a
typical sample (a small function) of my code with comments and would like it
if others could do the same.


;;;--------------------------------------------------------------------;
;;; Function:-----VPLIMITS
;
;;;--------------------------------------------------------------------;
;;; Function which returns the model space coordinates of the lower ;
;;; left corner of an active viewport and the upper right corner of
;
;;; the same as a list containing two elements, each a point.
;
;;;
;
;;; EX. Command: (vplimits)
;
;;; ((-31.5033 -17.8231 0.0) (44.0824 27.1675 0.0)) ;
;;;
;
;;; You can therefore use the CAR function to return the lower left ;
;;; corner and the cadr function to return the upper right corner
;
;;;
;
;;; NOTE: If this command is used in a polygonal viewport the ;
;;; returned coordinates will correspond to the model space
;
;;; corners of a box which would completly enclose the region ;
;;; viewed
;
;;;---------------------------------------------------------------------;
;;; [000] Beginning of function defintion VPLIMITS with no arguments ;
;;; and the following local variables:
;
;;;
;
;;; CFUNCTION: Used by the error function to tell which
;
;;; function was running when the error function
;
;;; was called
;
;;; VPOBJECT: Stores the Viewport object corresponding to the ;
;;; papers space viewport that was active when the
;
;;; function was called
;
;;; ODAXLL: Stands for Odeh ActiveX Lower Left and stores ;
;;; both the ActiveX safearray coordinate and the
;
;;; Visual LISP list coordinate of the lower left
;
;;; corner
;
;;; ODAXUR: Contains the same data as ODAXLL except for the ;
;;; upper right corner
;
;;; [005] Appends the quoted string to the tracer file and sets the
;
;;; CFUNCTION variable to the same
;
;;; [010] Captures the currently active Paper Space viewport and
;
;;; stores a pointer to the object in the VPOBJECT variable
;
;;; [015] The vla-getboundingbox function is used to capture the
;
;;; lower left and upper right coorinates of a box which
;
;;; completly surrounds the viewport, these coordinates are in
;
;;; paper space
;
;;; [020] The vlax-safearray->list function is used to change the
;
;;; ActiveX data type safearray into the Visual LISP data type
;
;;; list data type, the result replaces the variable being
;
;;; changed
;
;;; [025] See [020] above
;
;;; [040] Translates the coordinates from paperspace UCS to the model
;
;;; space UCS
;
;;; [045] See [040] above
;
;;; [050] End of setq function call
;
;;; [055] Reduce the tracer files indentation level
;
;;; [060] Return a list with the two points
;
;;; [065] End of function definition VPLIMITS
;
;;;-------------------------------------------------------------------------
---;
(defun VPLIMITS (/ CFUNCTION VPOBJECT ODAXLL ODAXUR) ;[000]
(setq CFUNCTION (TRACERAPPEND "VPLimits in Utilities.lsp"))
;[005]
(setq VPOBJECT (ACTIVE "pviewport"))
;[010]
(vla-getboundingbox VPOBJECT 'ODAXLL 'ODAXUR)
;[015]
(setq ODAXLL (vlax-safearray->list ODAXLL)
;[020]
ODAXUR (vlax-safearray->list ODAXUR)
;[025]
ODAXLL (trans (trans ODAXLL 3 2) 2 1)
;[040]
ODAXUR (trans (trans ODAXUR 3 2) 2 1)
;[045]
)
;[050]
(L-)
;[055]
(list ODAXLL ODAXUR)
;[060]
)
;[065]

--
Mike King
Odeh Engineers, Inc.

[Anonymous]

What you are doing seems like overkill to me. In some instances you are
"re-writing" the help file. Anyone who is writing code should know how to
get the first and second element from a list of two things, I don't think
that needs to be explained. Too many comments makes the code really hard to
read and follow. IMO, the use of logical variable and function names goes a
long way. I generally include a header in the file, and unless the code is
really *complicated* I don't place comments through out the file. Like you
said, you spend more time commenting the file than you do actually writing
the code.

My $0.02

--
-Jason

Member of the Autodesk Discussion Forum Moderator Program


> ;;; the same as a list containing two elements, each a point.
> ;
> ;;;
> ;
> ;;; EX. Command: (vplimits)
> ;
> ;;; ((-31.5033 -17.8231 0.0) (44.0824 27.1675 0.0))
;
> ;;;
> ;
> ;;; You can therefore use the CAR function to return the lower left
;
> ;;; corner and the cadr function to return the upper right corner

[Anonymous]

I agree with you about commenting in the code, it is very distrcating. That
is why I only include line labels in the code and the actual comments in the
header, I think you are right though. People can always look things up in
the help. I would still like to see some examples or explanations of what
others are doing.

--
Mike King
Odeh Engineers, Inc.

[Anonymous]

Actually what would also be nice is some variable naming conventions that
are out there. I just use clearn names (like VIEWPORT_OBJECT) for a
viewport object but don't follow any conventions

--
Mike King
Odeh Engineers, Inc.

[Anonymous]

Michael,

For the header, I would suggest using the in-line comment pair and perhaps
explain args/variables at the function, e.g.:

;|
This is my header...
blah, blah, blah
|;

(defun MyCoolFunc (Arg1 ; reason for this arg
Arg2 ; reason for this arg
/ Var1) ; purpose of this variable
...)

The "keynoted" comments are too hard to follow, IMHO...

--
R. Robert Bell, MCSE
www.AcadX.com


"Michael King" wrote in message
news:A946E2CB82F259299CCDDA8807CD944F@in.WebX.maYIadrTaRb...
| I just wanted to ask the group what styles of comments / level of
commenting
| they employ. I am a very thorough commenter (which comes of having a very
| poor memory) and inclue a function header which describes the function and
| line by line comments for all my functions. This helps alot but I end up
| spending more time writing / maintaining my comments as I do writing and
| maintaining my code. What are the thoughts of the group? I have included
a
| typical sample (a small function) of my code with comments and would like
it
| if others could do the same.
|
|
| ;;;--------------------------------------------------------------------;
| ;;; Function:-----VPLIMITS
| ;
| ;;;--------------------------------------------------------------------;
| ;;; Function which returns the model space coordinates of the lower ;
| ;;; left corner of an active viewport and the upper right corner of
| ;
| ;;; the same as a list containing two elements, each a point.
| ;
| ;;;
| ;
| ;;; EX. Command: (vplimits)
| ;
| ;;; ((-31.5033 -17.8231 0.0) (44.0824 27.1675 0.0))
;
| ;;;
| ;
| ;;; You can therefore use the CAR function to return the lower left
;
| ;;; corner and the cadr function to return the upper right corner
| ;
| ;;;
| ;
| ;;; NOTE: If this command is used in a polygonal viewport the
;
| ;;; returned coordinates will correspond to the model space
| ;
| ;;; corners of a box which would completly enclose the region
;
| ;;; viewed
| ;
| ;;;---------------------------------------------------------------------;
| ;;; [000] Beginning of function defintion VPLIMITS with no arguments ;
| ;;; and the following local variables:
| ;
| ;;;
| ;
| ;;; CFUNCTION: Used by the error function to tell which
| ;
| ;;; function was running when the error function
| ;
| ;;; was called
| ;
| ;;; VPOBJECT: Stores the Viewport object corresponding to the ;
| ;;; papers space viewport that was active when the
| ;
| ;;; function was called
| ;
| ;;; ODAXLL: Stands for Odeh ActiveX Lower Left and stores ;
| ;;; both the ActiveX safearray coordinate and the
| ;
| ;;; Visual LISP list coordinate of the lower left
| ;
| ;;; corner
| ;
| ;;; ODAXUR: Contains the same data as ODAXLL except for the ;
| ;;; upper right corner
| ;
| ;;; [005] Appends the quoted string to the tracer file and sets the
| ;
| ;;; CFUNCTION variable to the same
| ;
| ;;; [010] Captures the currently active Paper Space viewport and
| ;
| ;;; stores a pointer to the object in the VPOBJECT variable
| ;
| ;;; [015] The vla-getboundingbox function is used to capture the
| ;
| ;;; lower left and upper right coorinates of a box which
| ;
| ;;; completly surrounds the viewport, these coordinates are in
| ;
| ;;; paper space
| ;
| ;;; [020] The vlax-safearray->list function is used to change the
| ;
| ;;; ActiveX data type safearray into the Visual LISP data type
| ;
| ;;; list data type, the result replaces the variable being
| ;
| ;;; changed
| ;
| ;;; [025] See [020] above
| ;
| ;;; [040] Translates the coordinates from paperspace UCS to the model
| ;
| ;;; space UCS
| ;
| ;;; [045] See [040] above
| ;
| ;;; [050] End of setq function call
| ;
| ;;; [055] Reduce the tracer files indentation level
| ;
| ;;; [060] Return a list with the two points
| ;
| ;;; [065] End of function definition VPLIMITS
| ;
|
;;;-------------------------------------------------------------------------
| ---;
| (defun VPLIMITS (/ CFUNCTION VPOBJECT ODAXLL ODAXUR) ;[000]
| (setq CFUNCTION (TRACERAPPEND "VPLimits in Utilities.lsp"))
| ;[005]
| (setq VPOBJECT (ACTIVE "pviewport"))
| ;[010]
| (vla-getboundingbox VPOBJECT 'ODAXLL 'ODAXUR)
| ;[015]
| (setq ODAXLL (vlax-safearray->list ODAXLL)
| ;[020]
| ODAXUR (vlax-safearray->list ODAXUR)
| ;[025]
| ODAXLL (trans (trans ODAXLL 3 2) 2 1)
| ;[040]
| ODAXUR (trans (trans ODAXUR 3 2) 2 1)
| ;[045]
| )
| ;[050]
| (L-)
| ;[055]
| (list ODAXLL ODAXUR)
| ;[060]
| )
| ;[065]
|
| --
| Mike King
| Odeh Engineers, Inc.
|
|

[Anonymous]

I'm a very poor commenter so when I started to read your post I thought that
I'd say any level of commenting would be good. After reading your sample
I've changed my mind. I think I'd say you've gone a little overboard. If it
works for you, no problem. At least your not sitting there saying "Now what
did I mean to do here?". But maybe you could cut down a little.
Remember. You asked.

Allen


"Michael King" wrote in message
news:A946E2CB82F259299CCDDA8807CD944F@in.WebX.maYIadrTaRb...
> I just wanted to ask the group what styles of comments / level of
commenting
> they employ. I am a very thorough commenter (which comes of having a very
> poor memory) and inclue a function header which describes the function and
> line by line comments for all my functions. This helps alot but I end up
> spending more time writing / maintaining my comments as I do writing and
> maintaining my code. What are the thoughts of the group? I have included
a
> typical sample (a small function) of my code with comments and would like
it
> if others could do the same.

[Anonymous]

An example of what I try to stick to:

; Jason Piercey 2002.
; Return: a selection set of dimensions/leaders or nil
; Argument: list of three things ([Style] [Tab] [Text])
; Style: a string speciying a dimstyle name(s)
; Tab: if a non nil value is supplied the selection
; set is restricted to the current tab
; Text: Include associated text for leaders in selection set
; Examples:
; (JRP:Dimss (list "Standard$0 T)) <-linear dimensions
; (JRP:Dimss (list "Standard$0,Standard$7 T T)) <-linear and leaders
; (JRP:Dimss (list "Standard* T T)) <-all dims

(defun JRP:Dimss (ArgLst / Style Tab Text ss i Rtn Ename EntLst Name Tmp)
(mapcar 'set '(Style Tab Text) ArgLst)
(if Tab
(setq ss (ssget "x" (list '(0 . "DIMENSION,LEADER")
(cons 410 (getvar "ctab")))))
(setq ss (ssget "x" (list '(0 . "DIMENSION,LEADER"))))
)
(if ss
(progn
(setq i -1 Rtn (ssadd))
(repeat (sslength ss)
(setq Ename (ssname ss (setq i (1+ i)))
EntLst (entget Ename)
Name (strcase (cdr (assoc 3 EntLst)))
)
(if (wcmatch Name (strcase Style))
(progn
(ssadd Ename Rtn)
(if (and Text
(equal '(0 . "LEADER") (assoc 0 EntLst))
(setq Tmp (entget (cdr (assoc 340 EntLst))))
)
(ssadd (cdr (assoc -1 Tmp)) Rtn)
)
)
)
)
(if (> (sslength Rtn) 0) Rtn)
)
)
)



--
-Jason

Member of the Autodesk Discussion Forum Moderator Program


> I would still like to see some examples or explanations of what
> others are doing.

[Anonymous]

So you really don't use any comments in the code itself... maybe that comes
with experience but for now I find that I very quickly forget what a
particular structure does (loops or deeply nested functions) and spend as
much time figuring it out as I would commenting it. Perhaps I will take a
middle road and just use a few strategic comments in the code to refresh my
memory.


Mike King
Odeh Engineers, Inc.

[Anonymous]

For variable names I like to use stuff like:

Ent = a selection like (entsel)
EntLst = an entity list
Ename = an entity name
Obj = an object
Tmp = temporary value, not that important
ss = selection set
i = an index
Cnt = another "index" (if 'i' is already in use)

I think that if you browse some of the threads in this group you will get a
feel for how most folks handle things. Some have very explicit styles and
you can tell who's code it is without looking.


--
-Jason

Member of the Autodesk Discussion Forum Moderator Program


"Michael King" wrote in message
news:93B4C6AAC65041486FE77254D1C47D45@in.WebX.maYIadrTaRb...
> Actually what would also be nice is some variable naming conventions that
> are out there. I just use clearn names (like VIEWPORT_OBJECT) for a
> viewport object but don't follow any conventions
>
> --
> Mike King
> Odeh Engineers, Inc.
>
>

[Anonymous]

Thanks Jason, I probably will do that. I have only been writing for about a
year now so I am still developing my style but I want to at least get some
standards in place so things are consistant. I appreciate your posts.

--
Mike King
Odeh Engineers, Inc.

[Anonymous]

Here is a sample of mine:

;|

PSLimits.lsp

Version history
1.0 2002/04/01 Initial release.

Returns plottable area of specified layout, in inches.

Dependencies: rrbI:axDoc, rrbI:GetVar
Usage: (rrbI:PSLimits LayoutN)
Arguments: LayoutN string, layout name to return plottable area from.
Returns: list, area in inches.

Copyright © 2002 by R. Robert Bell.

Permission to use this software for any purpose and without fee is hereby
granted,
provided that the above copyright notice appears in all copies and that both
the copyright notice and the limited warranty and restricted rights notice
below
appear in all supporting documentation.

R. ROBERT BELL PROVIDES THIS PROGRAM "AS IS" AND WITH ALL FAULTS.
R. ROBERT BELL SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE.
R. ROBERT BELL DOES NOT WARRANT THAT THE OPERATION OF THE PROGRAM
WILL BE UNINTERRUPTED OR ERROR FREE.

RobertB@acadx.com

|;

(defun rrbI:PSLimits (LayoutN / objCTab LL UR Width Height)
(setq objCTab (vla-Item (vla-Get-Layouts (rrbI:axDoc)) LayoutN))
(vla-GetPaperMargins objCTab 'LL 'UR)
(setq LL (vlax-SafeArray->List LL)
UR (vlax-SafeArray->List UR))
(cond ((or (= ac0degrees (vla-Get-PlotRotation objCTab))
(= ac180degrees (vla-Get-PlotRotation objCTab)))
(vla-GetPaperSize objCTab 'Width 'Height))
(T
(setq LL (reverse LL)
UR (reverse UR))
(vla-GetPaperSize objCTab 'Height 'Width)))
(mapcar (function (lambda (x) (cvunit x "mm" "inch")))
(list (- Width (car LL) (car UR)) (- Height (cadr LL) (cadr UR)))))


--
R. Robert Bell, MCSE
www.AcadX.com


"Michael King" wrote in message
news:9E1AF77688F31B282A16601203484D1B@in.WebX.maYIadrTaRb...
| I agree with you about commenting in the code, it is very distrcating.
That
| is why I only include line labels in the code and the actual comments in
the
| header, I think you are right though. People can always look things up in
| the help. I would still like to see some examples or explanations of what
| others are doing.
|
| --
| Mike King
| Odeh Engineers, Inc.
|
|

[Anonymous]

Do you include a version number and date with every function? I can see how
this could be useful since I back up my lsp files often and it would often
be useful to be able to revert to a specific version... do you keep track of
the changes you make on any particular version anywhere? Thanks for your
time.

--
Mike King
Odeh Engineers, Inc.

"R. Robert Bell" wrote in message
news:FF56D9621925881B4F437C3FAE569695@in.WebX.maYIadrTaRb...
> Here is a sample of mine:
>
> ;|
>
> PSLimits.lsp
>
> Version history
> 1.0 2002/04/01 Initial release.
>
> Returns plottable area of specified layout, in inches.
>
> Dependencies: rrbI:axDoc, rrbI:GetVar
> Usage: (rrbI:PSLimits LayoutN)
> Arguments: LayoutN string, layout name to return plottable area from.
> Returns: list, area in inches.

[Anonymous]

At the top of each file that represents a stand-alone command function, I keep a
detailed record of the creation and revisions with dates. Other than that, the
only comments I add to my code are:
a) What a sub-function does if it's not obvious, plus credits.
b) Sub-function revisions and dates, plus credits.
c) Notes about special situations.
d) Reminders:
As to what a DXF code represents (dimension data drives me nuts).
As to global or Boolean variables.

--
John Uhden, Cadlantic/formerly CADvantage
http://www.cadlantic.com
Sea Girt, NJ


"Michael King" wrote in message
news:A946E2CB82F259299CCDDA8807CD944F@in.WebX.maYIadrTaRb...
> I just wanted to ask the group what styles of comments / level of commenting
> they employ. I am a very thorough commenter (which comes of having a very
> poor memory) and inclue a function header which describes the function and
> line by line comments for all my functions. This helps alot but I end up
> spending more time writing / maintaining my comments as I do writing and
> maintaining my code. What are the thoughts of the group? I have included a
> typical sample (a small function) of my code with comments and would like it
> if others could do the same.

[Anonymous]

I feel the more Global Variables require more comments.
I am working on a fairly long bit of code and have found that
when setting a global variable it is nice to say why and what other
functions it will affect. Of course that brings up another question-
Knowing when to use local or global. I find myself using global
way to much.


--
Ken Alexander
Acad 2000
Win 2000
"Michael King" wrote in message
news:A946E2CB82F259299CCDDA8807CD944F@in.WebX.maYIadrTaRb...
> I just wanted to ask the group what styles of comments / level of
commenting
> they employ. I am a very thorough commenter (which comes of having a very
> poor memory) and inclue a function header which describes the function and
> line by line comments for all my functions. This helps alot but I end up
> spending more time writing / maintaining my comments as I do writing and
> maintaining my code. What are the thoughts of the group? I have included
a
> typical sample (a small function) of my code with comments and would like
it
> if others could do the same.
>
>
> ;;;--------------------------------------------------------------------;
> ;;; Function:-----VPLIMITS
> ;
> ;;;--------------------------------------------------------------------;
> ;;; Function which returns the model space coordinates of the lower ;
> ;;; left corner of an active viewport and the upper right corner of
> ;
> ;;; the same as a list containing two elements, each a point.
> ;
> ;;;
> ;
> ;;; EX. Command: (vplimits)
> ;
> ;;; ((-31.5033 -17.8231 0.0) (44.0824 27.1675 0.0))
;
> ;;;
> ;
> ;;; You can therefore use the CAR function to return the lower left
;
> ;;; corner and the cadr function to return the upper right corner
> ;
> ;;;
> ;
> ;;; NOTE: If this command is used in a polygonal viewport the
;
> ;;; returned coordinates will correspond to the model space
> ;
> ;;; corners of a box which would completly enclose the region
;
> ;;; viewed
> ;
> ;;;---------------------------------------------------------------------;
> ;;; [000] Beginning of function defintion VPLIMITS with no arguments ;
> ;;; and the following local variables:
> ;
> ;;;
> ;
> ;;; CFUNCTION: Used by the error function to tell which
> ;
> ;;; function was running when the error function
> ;
> ;;; was called
> ;
> ;;; VPOBJECT: Stores the Viewport object corresponding to the ;
> ;;; papers space viewport that was active when the
> ;
> ;;; function was called
> ;
> ;;; ODAXLL: Stands for Odeh ActiveX Lower Left and stores ;
> ;;; both the ActiveX safearray coordinate and the
> ;
> ;;; Visual LISP list coordinate of the lower left
> ;
> ;;; corner
> ;
> ;;; ODAXUR: Contains the same data as ODAXLL except for the ;
> ;;; upper right corner
> ;
> ;;; [005] Appends the quoted string to the tracer file and sets the
> ;
> ;;; CFUNCTION variable to the same
> ;
> ;;; [010] Captures the currently active Paper Space viewport and
> ;
> ;;; stores a pointer to the object in the VPOBJECT variable
> ;
> ;;; [015] The vla-getboundingbox function is used to capture the
> ;
> ;;; lower left and upper right coorinates of a box which
> ;
> ;;; completly surrounds the viewport, these coordinates are in
> ;
> ;;; paper space
> ;
> ;;; [020] The vlax-safearray->list function is used to change the
> ;
> ;;; ActiveX data type safearray into the Visual LISP data type
> ;
> ;;; list data type, the result replaces the variable being
> ;
> ;;; changed
> ;
> ;;; [025] See [020] above
> ;
> ;;; [040] Translates the coordinates from paperspace UCS to the model
> ;
> ;;; space UCS
> ;
> ;;; [045] See [040] above
> ;
> ;;; [050] End of setq function call
> ;
> ;;; [055] Reduce the tracer files indentation level
> ;
> ;;; [060] Return a list with the two points
> ;
> ;;; [065] End of function definition VPLIMITS
> ;
>
;;;-------------------------------------------------------------------------
> ---;
> (defun VPLIMITS (/ CFUNCTION VPOBJECT ODAXLL ODAXUR) ;[000]
> (setq CFUNCTION (TRACERAPPEND "VPLimits in Utilities.lsp"))
> ;[005]
> (setq VPOBJECT (ACTIVE "pviewport"))
> ;[010]
> (vla-getboundingbox VPOBJECT 'ODAXLL 'ODAXUR)
> ;[015]
> (setq ODAXLL (vlax-safearray->list ODAXLL)
> ;[020]
> ODAXUR (vlax-safearray->list ODAXUR)
> ;[025]
> ODAXLL (trans (trans ODAXLL 3 2) 2 1)
> ;[040]
> ODAXUR (trans (trans ODAXUR 3 2) 2 1)
> ;[045]
> )
> ;[050]
> (L-)
> ;[055]
> (list ODAXLL ODAXUR)
> ;[060]
> )
> ;[065]
>
> --
> Mike King
> Odeh Engineers, Inc.
>
>

[Anonymous]

If it was a significant change, I print the original version and hold that
until the next major rev...

--
R. Robert Bell, MCSE
www.AcadX.com


"Michael King" wrote in message
news:093D3CCA5A4E7074BB0740A5601508F1@in.WebX.maYIadrTaRb...
| Do you include a version number and date with every function? I can see
how
| this could be useful since I back up my lsp files often and it would often
| be useful to be able to revert to a specific version... do you keep track
of
| the changes you make on any particular version anywhere? Thanks for your
| time.
|
| --
| Mike King
| Odeh Engineers, Inc.
|
| "R. Robert Bell" wrote in message
| news:FF56D9621925881B4F437C3FAE569695@in.WebX.maYIadrTaRb...
| > Here is a sample of mine:
| >
| > ;|
| >
| > PSLimits.lsp
| >
| > Version history
| > 1.0 2002/04/01 Initial release.
| >
| > Returns plottable area of specified layout, in inches.
| >
| > Dependencies: rrbI:axDoc, rrbI:GetVar
| > Usage: (rrbI:PSLimits LayoutN)
| > Arguments: LayoutN string, layout name to return plottable area from.
| > Returns: list, area in inches.
|
|
|

[Anonymous]

You should be able to avoid most global variables in an application by
writing your functions to accept the former globals as arguments...

--
R. Robert Bell, MCSE
www.AcadX.com


"Ken Alexander" wrote in message
news:AECE7C47DB5CE48FBD9E4AFDEF6A2D40@in.WebX.maYIadrTaRb...
| I feel the more Global Variables require more comments.
| I am working on a fairly long bit of code and have found that
| when setting a global variable it is nice to say why and what other
| functions it will affect. Of course that brings up another question-
| Knowing when to use local or global. I find myself using global
| way to much.
|
|
| --
| Ken Alexander
| Acad 2000
| Win 2000
| "Michael King" wrote in message
| news:A946E2CB82F259299CCDDA8807CD944F@in.WebX.maYIadrTaRb...
| > I just wanted to ask the group what styles of comments / level of
| commenting
| > they employ. I am a very thorough commenter (which comes of having a
very
| > poor memory) and inclue a function header which describes the function
and
| > line by line comments for all my functions. This helps alot but I end
up
| > spending more time writing / maintaining my comments as I do writing and
| > maintaining my code. What are the thoughts of the group? I have
included
| a
| > typical sample (a small function) of my code with comments and would
like
| it
| > if others could do the same.
| >
| >
| > ;;;--------------------------------------------------------------------;
| > ;;; Function:-----VPLIMITS
| > ;
| > ;;;--------------------------------------------------------------------;
| > ;;; Function which returns the model space coordinates of the lower ;
| > ;;; left corner of an active viewport and the upper right corner of
| > ;
| > ;;; the same as a list containing two elements, each a point.
| > ;
| > ;;;
| > ;
| > ;;; EX. Command: (vplimits)
| > ;
| > ;;; ((-31.5033 -17.8231 0.0) (44.0824 27.1675 0.0))
| ;
| > ;;;
| > ;
| > ;;; You can therefore use the CAR function to return the lower left
| ;
| > ;;; corner and the cadr function to return the upper right corner
| > ;
| > ;;;
| > ;
| > ;;; NOTE: If this command is used in a polygonal viewport the
| ;
| > ;;; returned coordinates will correspond to the model space
| > ;
| > ;;; corners of a box which would completly enclose the region
| ;
| > ;;; viewed
| > ;
| >
;;;---------------------------------------------------------------------;
| > ;;; [000] Beginning of function defintion VPLIMITS with no arguments ;
| > ;;; and the following local variables:
| > ;
| > ;;;
| > ;
| > ;;; CFUNCTION: Used by the error function to tell which
| > ;
| > ;;; function was running when the error function
| > ;
| > ;;; was called
| > ;
| > ;;; VPOBJECT: Stores the Viewport object corresponding to the
;
| > ;;; papers space viewport that was active when the
| > ;
| > ;;; function was called
| > ;
| > ;;; ODAXLL: Stands for Odeh ActiveX Lower Left and stores
;
| > ;;; both the ActiveX safearray coordinate and the
| > ;
| > ;;; Visual LISP list coordinate of the lower left
| > ;
| > ;;; corner
| > ;
| > ;;; ODAXUR: Contains the same data as ODAXLL except for the ;
| > ;;; upper right corner
| > ;
| > ;;; [005] Appends the quoted string to the tracer file and sets the
| > ;
| > ;;; CFUNCTION variable to the same
| > ;
| > ;;; [010] Captures the currently active Paper Space viewport and
| > ;
| > ;;; stores a pointer to the object in the VPOBJECT variable
| > ;
| > ;;; [015] The vla-getboundingbox function is used to capture the
| > ;
| > ;;; lower left and upper right coorinates of a box which
| > ;
| > ;;; completly surrounds the viewport, these coordinates are in
| > ;
| > ;;; paper space
| > ;
| > ;;; [020] The vlax-safearray->list function is used to change the
| > ;
| > ;;; ActiveX data type safearray into the Visual LISP data type
| > ;
| > ;;; list data type, the result replaces the variable being
| > ;
| > ;;; changed
| > ;
| > ;;; [025] See [020] above
| > ;
| > ;;; [040] Translates the coordinates from paperspace UCS to the model
| > ;
| > ;;; space UCS
| > ;
| > ;;; [045] See [040] above
| > ;
| > ;;; [050] End of setq function call
| > ;
| > ;;; [055] Reduce the tracer files indentation level
| > ;
| > ;;; [060] Return a list with the two points
| > ;
| > ;;; [065] End of function definition VPLIMITS
| > ;
| >
|
;;;-------------------------------------------------------------------------
| > ---;
| > (defun VPLIMITS (/ CFUNCTION VPOBJECT ODAXLL ODAXUR) ;[000]
| > (setq CFUNCTION (TRACERAPPEND "VPLimits in Utilities.lsp"))
| > ;[005]
| > (setq VPOBJECT (ACTIVE "pviewport"))
| > ;[010]
| > (vla-getboundingbox VPOBJECT 'ODAXLL 'ODAXUR)
| > ;[015]
| > (setq ODAXLL (vlax-safearray->list ODAXLL)
| > ;[020]
| > ODAXUR (vlax-safearray->list ODAXUR)
| > ;[025]
| > ODAXLL (trans (trans ODAXLL 3 2) 2 1)
| > ;[040]
| > ODAXUR (trans (trans ODAXUR 3 2) 2 1)
| > ;[045]
| > )
| > ;[050]
| > (L-)
| > ;[055]
| > (list ODAXLL ODAXUR)
| > ;[060]
| > )
| > ;[065]
| >
| > --
| > Mike King
| > Odeh Engineers, Inc.
| >
| >
|

[Anonymous]

In one set of routines which set up drawings based on settings from dialog
boxes, that involved a great many seperate functions sharing data, I created
a list of dotted pairs which contained all of the needed data and simply
passed this as an argument every time a function was called and returned it
to the calling function which then captured it in its own local variable of
the same name. This enabled me to save a great many global variables. I
created a couple special functions for handling this data structure quickly
and effectivly and now use the same principle whenever I need to manage
large amounts of info between seperate functions.

--
Mike King
Odeh Engineers, Inc.

[Anonymous]

I work on some large LISP files and have found the lack of comment a very
time-consuming issues. I think you can over do comments though. Most of
the time I like to see comments at the beginning of every function that
describes what that function does and any argument that are needed to call
that function and what, if anything, return value that function has. I also
like comments throughout the code in areas where it might get confusing or
at the start of sections the do a specific job like:

;* Step through all attributes until the CATNO attribute is found.

Comments become a lot more necessary if you are working in a group with
multiple programmer working on the same code. I have looked at some large
LISP programs, thousands and thousands of lines, with few comments not even
comments on what the functions do, and this is very time consuming.

I like to see good indentation to make the functions easier to read also.
Good variable naming is important also. If your variable names are
descriptive enough, there is no need to comment them. I like to use
variables like LineEntity. I capitalize the first letter of each word to
make them standout a little more.

Now since I have bored everybody, I will go.


"Michael King" wrote in message
news:A946E2CB82F259299CCDDA8807CD944F@in.WebX.maYIadrTaRb...
> I just wanted to ask the group what styles of comments / level of
commenting
> they employ. I am a very thorough commenter (which comes of having a very
> poor memory) and inclue a function header which describes the function and
> line by line comments for all my functions. This helps alot but I end up
> spending more time writing / maintaining my comments as I do writing and
> maintaining my code. What are the thoughts of the group? I have included
a
> typical sample (a small function) of my code with comments and would like
it
> if others could do the same.
>
>
> ;;;--------------------------------------------------------------------;
> ;;; Function:-----VPLIMITS
> ;
> ;;;--------------------------------------------------------------------;
> ;;; Function which returns the model space coordinates of the lower ;
> ;;; left corner of an active viewport and the upper right corner of
> ;
> ;;; the same as a list containing two elements, each a point.
> ;
> ;;;
> ;
> ;;; EX. Command: (vplimits)
> ;
> ;;; ((-31.5033 -17.8231 0.0) (44.0824 27.1675 0.0))
;
> ;;;
> ;
> ;;; You can therefore use the CAR function to return the lower left
;
> ;;; corner and the cadr function to return the upper right corner
> ;
> ;;;
> ;
> ;;; NOTE: If this command is used in a polygonal viewport the
;
> ;;; returned coordinates will correspond to the model space
> ;
> ;;; corners of a box which would completly enclose the region
;
> ;;; viewed
> ;
> ;;;---------------------------------------------------------------------;
> ;;; [000] Beginning of function defintion VPLIMITS with no arguments ;
> ;;; and the following local variables:
> ;
> ;;;
> ;
> ;;; CFUNCTION: Used by the error function to tell which
> ;
> ;;; function was running when the error function
> ;
> ;;; was called
> ;
> ;;; VPOBJECT: Stores the Viewport object corresponding to the ;
> ;;; papers space viewport that was active when the
> ;
> ;;; function was called
> ;
> ;;; ODAXLL: Stands for Odeh ActiveX Lower Left and stores ;
> ;;; both the ActiveX safearray coordinate and the
> ;
> ;;; Visual LISP list coordinate of the lower left
> ;
> ;;; corner
> ;
> ;;; ODAXUR: Contains the same data as ODAXLL except for the ;
> ;;; upper right corner
> ;
> ;;; [005] Appends the quoted string to the tracer file and sets the
> ;
> ;;; CFUNCTION variable to the same
> ;
> ;;; [010] Captures the currently active Paper Space viewport and
> ;
> ;;; stores a pointer to the object in the VPOBJECT variable
> ;
> ;;; [015] The vla-getboundingbox function is used to capture the
> ;
> ;;; lower left and upper right coorinates of a box which
> ;
> ;;; completly surrounds the viewport, these coordinates are in
> ;
> ;;; paper space
> ;
> ;;; [020] The vlax-safearray->list function is used to change the
> ;
> ;;; ActiveX data type safearray into the Visual LISP data type
> ;
> ;;; list data type, the result replaces the variable being
> ;
> ;;; changed
> ;
> ;;; [025] See [020] above
> ;
> ;;; [040] Translates the coordinates from paperspace UCS to the model
> ;
> ;;; space UCS
> ;
> ;;; [045] See [040] above
> ;
> ;;; [050] End of setq function call
> ;
> ;;; [055] Reduce the tracer files indentation level
> ;
> ;;; [060] Return a list with the two points
> ;
> ;;; [065] End of function definition VPLIMITS
> ;
>
;;;-------------------------------------------------------------------------
> ---;
> (defun VPLIMITS (/ CFUNCTION VPOBJECT ODAXLL ODAXUR) ;[000]
> (setq CFUNCTION (TRACERAPPEND "VPLimits in Utilities.lsp"))
> ;[005]
> (setq VPOBJECT (ACTIVE "pviewport"))
> ;[010]
> (vla-getboundingbox VPOBJECT 'ODAXLL 'ODAXUR)
> ;[015]
> (setq ODAXLL (vlax-safearray->list ODAXLL)
> ;[020]
> ODAXUR (vlax-safearray->list ODAXUR)
> ;[025]
> ODAXLL (trans (trans ODAXLL 3 2) 2 1)
> ;[040]
> ODAXUR (trans (trans ODAXUR 3 2) 2 1)
> ;[045]
> )
> ;[050]
> (L-)
> ;[055]
> (list ODAXLL ODAXUR)
> ;[060]
> )
> ;[065]
>
> --
> Mike King
> Odeh Engineers, Inc.
>
>

[Anonymous]

Example attached.

I like the commenting styles of:
Steve Johnson
Jon Fleming

(at least)

& have tried to model my comments on their examples (but I usually don't write
the "book" that Jon does).

At minimum, I believe all functions should be well documented in a function
header, & the general program or flow of control should be sketched out in the
program itself. Makes it much easier to try to remember what you did when you
come back to the program next year or the year after to modify it.

Also, I find myself writing the comments first, in many cases. IOW, the
comments are sort of an informal specification of the program & help me to
organize thoughts while writing the program.

[Anonymous]

I don't quite understand your meaning. If you had this sennerio, how would
you set your variables, local or global? Keeping in mind I am using over 100
different variables in over 100 different sub functions.

(defun C:mainfun ()
(setq a "yes"
b "no"
c "maybe")
)

(defun subfun1 ()
(if (= a "yes")
(do this)
(else this)
)
)

(defun subfun2 ()
(if(= b "no")
(do this)
(else this)
)
)

--
Ken Alexander
Acad 2000
Win 2000
"R. Robert Bell" wrote in message
news:009C610B415D1CCAF43C8C7836ED51B6@in.WebX.maYIadrTaRb...
> You should be able to avoid most global variables in an application by
> writing your functions to accept the former globals as arguments...
>
> --
> R. Robert Bell, MCSE
> www.AcadX.com
>
>
> "Ken Alexander" wrote in message
> news:AECE7C47DB5CE48FBD9E4AFDEF6A2D40@in.WebX.maYIadrTaRb...
> | I feel the more Global Variables require more comments.
> | I am working on a fairly long bit of code and have found that
> | when setting a global variable it is nice to say why and what other
> | functions it will affect. Of course that brings up another question-
> | Knowing when to use local or global. I find myself using global
> | way to much.
> |
> |
> | --
> | Ken Alexander
> | Acad 2000
> | Win 2000
> | "Michael King" wrote in message
> | news:A946E2CB82F259299CCDDA8807CD944F@in.WebX.maYIadrTaRb...
> | > I just wanted to ask the group what styles of comments / level of
> | commenting
> | > they employ. I am a very thorough commenter (which comes of having a
> very
> | > poor memory) and inclue a function header which describes the function
> and
> | > line by line comments for all my functions. This helps alot but I end
> up
> | > spending more time writing / maintaining my comments as I do writing
and
> | > maintaining my code. What are the thoughts of the group? I have
> included
> | a
> | > typical sample (a small function) of my code with comments and would
> like
> | it
> | > if others could do the same.
> | >
> | >
> | >
;;;--------------------------------------------------------------------;
> | > ;;; Function:-----VPLIMITS
> | > ;
> | >
;;;--------------------------------------------------------------------;
> | > ;;; Function which returns the model space coordinates of the lower
;
> | > ;;; left corner of an active viewport and the upper right corner of
> | > ;
> | > ;;; the same as a list containing two elements, each a point.
> | > ;
> | > ;;;
> | > ;
> | > ;;; EX. Command: (vplimits)
> | > ;
> | > ;;; ((-31.5033 -17.8231 0.0) (44.0824 27.1675 0.0))
> | ;
> | > ;;;
> | > ;
> | > ;;; You can therefore use the CAR function to return the lower left
> | ;
> | > ;;; corner and the cadr function to return the upper right corner
> | > ;
> | > ;;;
> | > ;
> | > ;;; NOTE: If this command is used in a polygonal viewport the
> | ;
> | > ;;; returned coordinates will correspond to the model space
> | > ;
> | > ;;; corners of a box which would completly enclose the region
> | ;
> | > ;;; viewed
> | > ;
> | >
> ;;;---------------------------------------------------------------------;
> | > ;;; [000] Beginning of function defintion VPLIMITS with no arguments
;
> | > ;;; and the following local variables:
> | > ;
> | > ;;;
> | > ;
> | > ;;; CFUNCTION: Used by the error function to tell which
> | > ;
> | > ;;; function was running when the error function
> | > ;
> | > ;;; was called
> | > ;
> | > ;;; VPOBJECT: Stores the Viewport object corresponding to
the
> ;
> | > ;;; papers space viewport that was active when the
> | > ;
> | > ;;; function was called
> | > ;
> | > ;;; ODAXLL: Stands for Odeh ActiveX Lower Left and stores
> ;
> | > ;;; both the ActiveX safearray coordinate and the
> | > ;
> | > ;;; Visual LISP list coordinate of the lower left
> | > ;
> | > ;;; corner
> | > ;
> | > ;;; ODAXUR: Contains the same data as ODAXLL except for the
;
> | > ;;; upper right corner
> | > ;
> | > ;;; [005] Appends the quoted string to the tracer file and sets the
> | > ;
> | > ;;; CFUNCTION variable to the same
> | > ;
> | > ;;; [010] Captures the currently active Paper Space viewport and
> | > ;
> | > ;;; stores a pointer to the object in the VPOBJECT variable
> | > ;
> | > ;;; [015] The vla-getboundingbox function is used to capture the
> | > ;
> | > ;;; lower left and upper right coorinates of a box which
> | > ;
> | > ;;; completly surrounds the viewport, these coordinates are in
> | > ;
> | > ;;; paper space
> | > ;
> | > ;;; [020] The vlax-safearray->list function is used to change the
> | > ;
> | > ;;; ActiveX data type safearray into the Visual LISP data type
> | > ;
> | > ;;; list data type, the result replaces the variable being
> | > ;
> | > ;;; changed
> | > ;
> | > ;;; [025] See [020] above
> | > ;
> | > ;;; [040] Translates the coordinates from paperspace UCS to the model
> | > ;
> | > ;;; space UCS
> | > ;
> | > ;;; [045] See [040] above
> | > ;
> | > ;;; [050] End of setq function call
> | > ;
> | > ;;; [055] Reduce the tracer files indentation level
> | > ;
> | > ;;; [060] Return a list with the two points
> | > ;
> | > ;;; [065] End of function definition VPLIMITS
> | > ;
> | >
> |
>
;;;-------------------------------------------------------------------------
> | > ---;
> | > (defun VPLIMITS (/ CFUNCTION VPOBJECT ODAXLL ODAXUR) ;[000]
> | > (setq CFUNCTION (TRACERAPPEND "VPLimits in Utilities.lsp"))
> | > ;[005]
> | > (setq VPOBJECT (ACTIVE "pviewport"))
> | > ;[010]
> | > (vla-getboundingbox VPOBJECT 'ODAXLL 'ODAXUR)
> | > ;[015]
> | > (setq ODAXLL (vlax-safearray->list ODAXLL)
> | > ;[020]
> | > ODAXUR (vlax-safearray->list ODAXUR)
> | > ;[025]
> | > ODAXLL (trans (trans ODAXLL 3 2) 2 1)
> | > ;[040]
> | > ODAXUR (trans (trans ODAXUR 3 2) 2 1)
> | > ;[045]
> | > )
> | > ;[050]
> | > (L-)
> | > ;[055]
> | > (list ODAXLL ODAXUR)
> | > ;[060]
> | > )
> | > ;[065]
> | >
> | > --
> | > Mike King
> | > Odeh Engineers, Inc.
> | >
> | >
> |
>
>