Topic: Comments

[Kerry]

AutoLISP Developer's Guide

Using the Visual LISP Environment
-->Developing Programs with Visual LISP
----->Formatting Code with Visual LISP
-------->Applying Formatting Options
----------->Applying Visual LISP Comment Styles

Any Comments ?

I'm wondering how many people vent about “Single-Semicolon" being used at 'Heading' or 'Current-Column' locations.
... I know, with some posted code,  I get tired of adding extra semicolons so code will format.

Why format ?.. It helps me to understand code flow.

also, How many people find the  ) ';_ Function-Closing' comment visually intrusive ?

[MP]

I never use the vlisp editor, so I'm not familiar with the heading, current column location thingy you refer to.

As for closing parenthesis comments, I absolutely loathe them. To me it just makes it a visual mess that is more difficult to visually parse and every time I see them I can't help but have a kind of animosity, unfair as that is, towards the code sporting it.

/my 2¢

[Kerry]

Code: [Select]

;;; heading or 0-column comment
;;; heading or 0-column comment
;;
(defun foo (x) ;|inline comment |;
   (list 1 2 3)                       ;comment-column comment
   ;;current-column comment
;;; heading or 0-column comment
   ) ;_ function-closing comment

[MP]

Thank you for explaining Kerry.

Ughhh.

I hate having an editor impose its style upon me, but conversely, I'm generally pretty anal how I format my code (though I fully acknowledge it has drifted somewhat over the years). Textpad has been a very accommodating editor, supporting, but not forcing "my style", whatever that is. Just the right amount of horsepower, customizability and lithe footprint to keep me happy. I've used Textpad ever since I abandoned Multi-Edit, which I had used for MANY, many years prior (from the good ol' DOS days). But I digress.

Anyway, assuming anyone ever loaded up any of my code in the vlisp editor, I apologize if it looks like crap therein.

[Kerry]

I hate having an editor impose its style upon me ..

Generally, the VLIDE, with my configuration, opens code up enough to breathe.

[personally]
Your formatting is a dream to work with.

[Kerry]

... and for the naysayers out there < you know who you are >
... I'm NOT setting myself up as the code police 

whatever works for me, may not work for you !

[nivuahc]

For me, the );_random closing comment thinger is very useful. I have a hard enough time keeping track of what I'm doing when I'm not writing code so it helps me see, at a glance, where something stops (or should).

Most of the time, I write something and then never look at it again for months. When I do look at it, I don't parse it like English so it's nice for me to have a guideline of sorts.

And that's all due to poor programming on my part, I'm sure, but it works for me.

[MP]

Generally, the VLIDE, with my configuration, opens code up enough to breathe.

Good to hear it empowers you -- you can certainly write effective and intelligent quality code using it, tho admittedly that's a little like saying you're a good driver because you have a red car.

[personally]
Your formatting is a dream to work with.

Wow, I didn't see that one coming. Thank you sir!

[Jeff_M]

[personally]{in response to MP's comment-jm}
Your formatting is a dream to work with.

While I wholeheartedly agree with this, I have never been able to force myself to code in anywhere close to MP's style. Too many spaces/tabs I reckon.

I like using the VLIDE, but it really irks me in that the autoformat will setup the code how I like it, then I'll go back and add/change/remove portions of the code and go to reformat it and the reformat looks NOTHING like the autoformat......
so I tend to steer clear of the format option.....which probably gets me included in the improper use of comments because I honestly don't pay that much attention to how many semicolons get placed  Then again, some would probably say that they have yet to find ANY worthwhile comments in my "code".

[nivuahc]

I once got so annoyed at the lack of comments in a batch of code I had held on to for years... that I spent several days doing nothing but writing comments. By the time I was finished, the code took up over twice the space on disk, all because of comments.

I laughed about it then erased it, routines and all. 

I was in one of those moods 

[MP]

When I first started coding lisp I was using an indent of 2 spaces. Coded that way for many years.

As my coding became more and more complex I found it increasingly difficult to discern the closing parenthesis.

So, like many folks I started adding the ...

(if predicate
    then
    else
) ;; end if

... closing parenthesis style comments (I have tons of legacy code that sports them that I loathe visiting, well over 30K lines).

But I became annoyed with it (as noted) and opted to go with an indent of 3 spaces.

While the clarity improved dramatically I found it annoying to switch back and forth from Power BASIC and Visual BASIC indents of 4 spaces to 3 spaces in LISP, so I said screw it, and just adopted 4 space indents globally.

Initially I found the 4 space indents almost prohibitive for LISPin', but then I adopted a more vertical style. That seemed to work well for me and I generally use that style to this day (in VB too). While it takes up a lot more ascii real estate there is no performance hit, and I can visually parse it faster than any other style I've observed. On hard copies it leaves ample room for pencilled comments too.

Mileages vary of course, this is just what worked out best for me.

< Thinking to self: Wow, why the heck am I so chatty tonight? >

[Kerry]

< ....> and I can visually parse it faster than any other style I've observed. On hard copies it leaves ample room for pencilled comments too.

Mileages vary of course, this is just what worked out best for me.

^^ Ditto me , though I prefer mine a little less sparse

I mentioned earlier code breathing. I actually meant giving the reader a chance to breathe , visually and mentally, when scanning it.

... sounds a little poetic perhaps, but works for me.

[Mark]

< Thinking to self: Wow, why the heck am I so chatty tonight? >

m e d i c a t i o n ?   


As a novice programmer I'm still trying to find a style. I like Michaels style very much, easy for me to read (  not to be confused with understanding it *grin* ) and I've tried to use said style but it never looks as good. The ')_defun' things bugs me as well, makes the code just to hard to follow. I like Kerrys format to, his code is just as easy for me to follow.

[T.Willey]

I hardly ever have comments except at the beginning so that I know what the code is supposed to do.  Sometimes I write code that I don't use, and then I go looking through to see what I have, so that is why I do that.

I used to code with two spaces, then I got tired of having to hit all the space, so now I use just one, and it seems to work for me.  If I wanted to use more spaces, I think I would go to one tab just so I can just hit one button.

But that is just me.

[Kerry]

hardly ever have comments except at the beginning so that I know what the code is supposed to do.

ditto, just as nudge notes ..

I used to code with two spaces, ..

.. generally 4 spaces indent and Tab=4 Spaces

[T.Willey]

.. generally 4 spaces indent and Tab=4 Spaces

Ah... Thanks.

Forgot to mentions that I code only in Notepad.

[Jürg Menzi]

As you know from my samples, I use comments very rarely. A function header says more than a comment behind every line.

Just my 2¢...

[GDF]

On a similar topic.........

If I can add to this a little. I carry this a step further and format my dcl code. When I first started playing around with dcl code, it was hard to follow the AutoCAD's way of dcl formatting. So I started to indent my code like a vlisp editor.

I could use a some inline commenting to the code. That is a good habit I will need to start.

Code: [Select]

/////////////////////////////////////////////////////////////////////////////////////

//To load master widgets used by Arch Program
@include "..\\ARCH.dcl"
dcl_settings :default_dcl_settings {audit_level=0;}

////////////////////////////////////////////////////////////////////////////////////

arch_program_multi_layerreactor_toggle
  :row {children_fixed_height=true; children_fixed_width=true;     
    :arch_multi {}
    :arch_curlaysetreactor {arch_curlaysetreactor;}
    :text_part {label="Leader";}
    :toggle {label="Poly"; key="poly";}
    :toggle {label="Bloc"; key="bloc";}
  }

////////////////////////////////////////////////////////////////////////////////////

ARCH_DIMS :dialog {key="set-title"; initial_focus="set-title"; width=93.3; height=21.875; 
  :row {width=33.875;
    :boxed_column {label="Control Settings"; children_fixed_width=true; children_fixed_height=true; 
      :text_part {label=" Change or Set Dimstyle";}   
      :row {children_alignment=top;
        :arch_55x55_image_252 {key="D1";}
        :arch_44x44_image_253 {key="D4";}
        :arch_44x44_image_253 {key="D3";}
        :arch_44x44_image_253 {key="D2";}
        :arch_35x35_image_15 {key="D5";}
        :arch_35x35_image_15 {key="D0";}
      }
    }
    :boxed_column {label="Dimension Commands";
      :text_part {label="  Cmd Name     Description";}
      :popup_list {key="commands-list"; width=51.5; tabs="11"; multiple_select=false;}
      :spacer {}
    }
  }
  :arch_program_multi_layerreactor_toggle {arch_program_multi_layerreactor_toggle;}

  :row {children_fixed_height=true; children_fixed_width=true;
    :column {       
      :boxed_row {label="Assoc Annotation - Ext Line Control";
        :column {children_fixed_width=true; children_fixed_height=true;
          :list_box {key="lb_notes"; width=19.5; height=8;} //label="Select Note"; height=8;
        }       
        :column {children_fixed_width=true; children_fixed_height=true;
          :row {
            :column { 
              :spacer {}
              :row {
                :toggle {key="updn";}
                :text_part {key="controlupdn"; width=6;}
              }             
              :row {           
                :toggle {key="onoff";}
                :text_part {key="controlonoff"; width=6;}   
              }           
            }
            :image {key="shpimgdims"; width=7.125; height=3.25; color=-15;}
          }       
          :edit_box {key="eb_note"; edit_width=15.5;}
          :row {children_fixed_width=true;
            :radio_button {label="Pick"; key="onoffaccept";}
            :button {label="Note"; key="dnoteaccept";}
          }
        }
      }
      :row {
        :button {label="Style"; key="dimsty"; fixed_width=true;}
        :arch_35x35_image_15 {key="dbl";}
        :arch_35x35_image_15 {key="dle";}
        :arch_35x35_image_15 {key="dimeq";}
        :arch_35x35_image_15 {key="grab";}
        :arch_35x35_image_15 {key="dimb";}
        :arch_35x35_image_15 {key="lldr";}
      }
    }
    :column {
      :boxed_column {label="Place Dimensions";       
        :row {children_fixed_height=true; children_fixed_width=true;
          :arch_65x65_image_252 {key="lin";}
          :arch_65x65_image_252 {key="qdim";}
          :arch_65x65_image_252 {key="con";}   
          :arch_65x65_image_252 {key="bas";} 
          :arch_65x65_image_252 {key="ali";} 
          :arch_65x65_image_252 {key="rot";}
        }
        :row {children_fixed_height=true; children_fixed_width=true;
          :arch_65x65_image_252 {key="cen";}
          :arch_65x65_image_252 {key="rad";}
          :arch_65x65_image_252 {key="dia";}
          :arch_65x65_image_252 {key="ang";}   
          :arch_65x65_image_252 {key="180";}   
          :arch_65x65_image_252 {key="ark";}     
        }
      }
      :row {children_fixed_height=true; children_fixed_width=true;
        :spacer {width=0.5;}       
        :column {             
          :text_part {label="Textstyle :";}
          :text_part {label="Height :";}
          :text_part {label="Dimstyle :";} 
        }           
        :column {
          :text_part {key="textinfo"; width=17.125;}
          :text_part {key="textsize"; width=17.125;}
          :arch_dsty {}
        }
        :column {
          :popup_list {key="sdimdec"; edit_width=15.5;}
          :row {
            :text_part {label="  Precision :";}
            :text_part {key="dimdec"; width=6.5;}
          }
        }
      }
    }
  }
  :arch_program_dimscale {arch_program_dimscale;}
}


Gary

[LE]

I like my code compact

Code: [Select]

(defun detail-enable  (/ lis_objs)
  (if (setq lis_objs
     (vlax-ldata-get
       "SYM-REACTORS"
       "DETAIL-SYMBOL"))
    (foreach sub  lis_objs
      (if (and (not (rwiz-partof (car sub)))
       (not (rwiz-partof (cadr sub)))
       (not (rwiz-partof (caddr sub))))
(detail-attach
  (car sub)
  (cadr sub)
  (caddr sub))))))

Basically is a habit, I learned that from Master Reinaldo Togores.

[CAB]

I like mine compact too.
I think it is what you are accustom to looking at & I think that your preferences change over time.
When I first started lisping in 2003 I benefited form excessive commenting. But now find it
somewhat annoying especially the ;_ function-closing comment. AS you get better at reading lisp the
function closing comments are only helpful in the cases where there is a large amount of code.
Like when you have 20 lines of code between the (if and the closing ) .
I think the larger the indent the less important the closing comment becomes as you can follow the
flow by looking at the indent. When the indent is only 2 spaces & 20 lines later the closing parentheses
is no longer obvious. The problem with VLIDE editor is that you get All or None in the closing comment.
I choose none & add them where I feel there will be helpful to me when I return to look at the code.
As for line comments, I still find them useful & when in doubt add them. That is for when you return
months later it helps understand the code. Let me just say that people like Michael & Kerry are VERY
fluent in the language & don't need much help in reading a chunk of new code. These folks have progressed
to the point where even this commenting gets in the way.  In there case a good explanation at the beginning
is all they need and the reading of the code, if well written, is obvious to them. I hope my assumptions
here are accurate but it is my take on the subject. I am still reading the words and phrases but at times
can read the entire sentences.

My conclusion is that you should turn off the "Auto Closing Comment" feature in VLIDE & add them sparingly.

[JohnK]

I like my formatting tight. I like to close my statmetnts after my last process.
(if (this is true)
  (Then do this stuff)
  (multiline
    (do this)
    (and this)
    (Dont forget this)
    (now we are done)) )
I tend to leave a space before the close as shown here, and my code tends to take the form of several blocks.

I too dislike the closing statment. However, im not against them being used. I see people new to lisp using them and that just shows they are thinking the process thru so I will not say that they are bad at all. I think new people should use all the formatting that makes them see the code easier. Because thats what its all about. Them not me or you. For instance. If MP was just learning code and he asked a question to Kerry and I (Do you see how I switched the rolls here *lol*). I dont think MP should have to worry about his formating at all. I say let him be comfortable with his style. And if I help him out and he uses closing statments I will assume his formatiing when correcting his code. (Note: Unless im trying to make an obvious statement in the code or something.)

[ElpanovEvgeniy]

I like standart formatting
(if lst
  (entmakex
    (append
      (list
        '(0 . "LWPOLYLINE")
        '(100 . "AcDbEntity")
        '(100 . "AcDbPolyline")
        (cons 90 (length lst))
        '(70 . 1)
      ) ;_  list
      (mapcar '(lambda (x) (cons 10 x)) lst)
    ) ;_  append
  ) ;_  entmakex
) ;_  if

[Bobby C. Jones]

I don't know if I'm getting crankier, crotchetier, or lazier but I can't hardly stand comments of any sort anymore.  I hate writting them, I hate reading them, and I sure as heck hate maintaining them.  I'll stop there so as not to show my bad side

I tend to write it off to my own naiveté, but the controversy that is stemmed by this topic and related topics never ceases to amaze me.  In groups other than the swamp this could well lead to fisticuffs

[ElpanovEvgeniy]

> Bobby C. Jones

I like to write one long program, instead of many short...
Now for me the cursor on 7442 line.
When the bracket is closed through 500 lines, comments to me help!

[Bobby C. Jones]

I like to write one long program, instead of many short...
Now for me the cursor on 7442 line.

Holy Carp!  Seriously, or are you yankin' my chain?  I'm extremely gullible you know.

I'm sitting here writting a bit of code and getting rather nervous because my procedure is getting close to 40 lines or so.  I'm actually guessing at the number of lines; I haven't counted those things in a very long time.

[ElpanovEvgeniy]

(foreach x lst
1
2
....
300
) ;_  foreach
Very much frequently...

[ElpanovEvgeniy]

More precisely. For me many small library programs (It is less than 40 lines).
And one big, processing of the list.

[ElpanovEvgeniy]

>Bobby C. Jones
Example as I work with lists...
http://www.theswamp.org/Themes/oxygen_tp/images/post/xx.gif

[Slim©]

*OFF TOPIC*

ElpanovEvgeniy

Try posting the image this way:

[ i m g ] http://www.theswamp.org/Themes/oxygen_tp/images/post/xx.gif [ / i m g ]

Remove the spaces...

And you get:

Hope that helps.

*CARRY ON*

[T.Willey]

*OFF TOPIC*

ElpanovEvgeniy

Try posting the image this way:

[ i m g ] http://www.theswamp.org/Themes/oxygen_tp/images/post/xx.gif [ / i m g ]

Remove the spaces...

And you get:

Hope that helps.

*CARRY ON*

[guess]
I think he was trying to get the link to the post he did in another thread, not the picture of the paper.
 [/guess]

[Slim©]

In that case try:

[ u r l = http://www.theswamp.org/index.php?topic=8963.msg115087#msg115087] THIS [ / u r l ]

THIS

[ElpanovEvgeniy]

http://www.theswamp.org/index.php?topic=8874.msg114586#msg114586

[JohnK]

Yes, in that situation i would use closing statments too.

[Bobby C. Jones]

Yes, in that situation i would use closing statments too.

I would tend to break out the code doing all those calculations into separate functions

[ElpanovEvgeniy]

In the beginning I create the list...
Then it(him) I shall update many times...
Then I end the program.

[Kerry]

Personally, I couldn't work in code with those line ending comments.

... because they are there, my eyes think they are important, then my brain says no they're not. After this happens a few times, I start to get annoyed with being interupted.

[ElpanovEvgeniy]

Everything, at a forum, do not like comments.
Very well!
I shall format the code for a forum...
 

[Kerry]

No No No No

Evgeniy,

People are just saying what they prefer, not telling you what to do !   

Normal conversation ...

[ElpanovEvgeniy]

>ALL
Select...
1

Code: [Select]

(defun multi-subst-fun (lst-i)
  (eval
    (list
      'defun
      'multi-subst
      '(lst)
      (list
        'mapcar
        (list 'function
              (list
                'lambda
                '(a)
                (cons
                  'cond
                  (reverse
                    (cons
                      '(t a)
                      (mapcar
                        '(lambda (a)
                           (list
                             (list
                               'equal
                               (car a)
                               'a
                             ) ;_  list
                             (cadr a)
                           ) ;_  list
                         ) ;_  lambda
                        lst-i
                      ) ;_  mapcar
                    ) ;_  cons
                  ) ;_  reverse
                ) ;_  cons
              ) ;_  list
        ) ;_  list
        'lst
      ) ;_  list
    ) ;_  list
  ) ;_  eval
) ;_  defun
;; do the test...
(multi-subst-fun '((1 "a") (3 "b")))

(multi-subst '(1 2 3 4 5))
(multi-subst '(1 6 4 3 7))
OR 2

Code: [Select]

(defun multi-subst-fun (lst-i)
  (eval
    (list
      'defun
      'multi-subst
      '(lst)
      (list
        'mapcar
        (list 'function
              (list
                'lambda
                '(a)
                (cons
                  'cond
                  (reverse
                    (cons
                      '(t a)
                      (mapcar
                        '(lambda (a)
                           (list
                             (list
                               'equal
                               (car a)
                               'a)
                             (cadr a)))
                        lst-i))))))
        'lst))))
;; do the test...
(multi-subst-fun '((1 "a") (3 "b")))

(multi-subst '(1 2 3 4 5))
(multi-subst '(1 6 4 3 7))


[JohnK]

Everything, at a forum, do not like comments.
Very well!
I shall format the code for a forum...
 

No. People like your code format. (They have said that its very nice.)

[LE]

>ALL
Select...
1

Code: [Select]

(defun multi-subst-fun (lst-i)
) ;_  defun
;; do the test...
(multi-subst-fun '((1 "a") (3 "b")))

(multi-subst '(1 2 3 4 5))
(multi-subst '(1 6 4 3 7))
OR 2

Code: [Select]

(defun multi-subst-fun (lst-i)
;; do the test...
(multi-subst-fun '((1 "a") (3 "b")))

(multi-subst '(1 2 3 4 5))
(multi-subst '(1 6 4 3 7))


Just being myself picky sometimes... that type of function is not readable, not easy to follow.

But that is just my opinion.

[ElpanovEvgeniy]

Only using comments, I do such functions...
    

[JohnK]

I choose: 1