AutoLISP 101 - Comments and Headers - Discussion

[peter]

This is where you all can discuss the AutoLISP 101 - Comments and Headers thread.



Comments and Headers


Please post comments to discussion thread

The first place I would like to start is comments.

I have adopted a standard where all of my lisp libraries and routines have a file header and function header comments.

The file header includes
1.) My name and year for copyright
2.) A disclaimer prohibiting unauthorized use
3.) An abstract that describes what is the purpose of the file or library
4.) The command line functions with descriptions (alphabetically) including hot key assignments
5.) The general functions with descriptions
6.) Version or last modified date

The function headers include
1.) Function Description

The functions are alphabetical (although I let the hot keys supersede their respective functions)

I use a noun first verb last function name to help organize the functions together when alphabetical.

I will talk more about function and variable naming.

So be honest how many of you actually take the time to create a LISP file header?

Code:

;___________________________________________________________________________________________________________|
    ;
    ; Written By: Peter Jamtgaard copyright 2017 All Rights Reserved
    ;___________________________________________________________________________________________________________|
    ;
    ; Any use by unauthorized person or business is strictly prohibited.
    ;___________________________________________________________________________________________________________|
    ; 
    ; Abstract: This routine will display an alert dialog with the words "Hello World" in it.
    ;___________________________________________________________________________________________________________|
    ;
    ; Command Line Function Header List
    ;___________________________________________________________________________________________________________|

    ;  Function and Description

    ;* C:HW 
    ;* Command Line Function (or hot key) to display Hello World Dialog

    ;* C:HelloWorld
    ;* Command Line Function to display Hello World Dialog

    ;___________________________________________________________________________________________________________|
    ;
    ; General Function Header List 
    ;___________________________________________________________________________________________________________|

    ;  Function, Arguments and Description

    ;* (DialogAlertHelloWorld)
    ;* Function to Display an Alert box with the words "Hello World"

    ;___________________________________________________________________________________________________________|
    ;
    ; Include Libraries List
    ;___________________________________________________________________________________________________________|

    ;* None

    ;___________________________________________________________________________________________________________|
    ;
    ; Include Data File List
    ;___________________________________________________________________________________________________________|

    ;* None

    ;___________________________________________________________________________________________________________|
    ;
    ; Include Dialog Control Language File List
    ;___________________________________________________________________________________________________________|

    ;* None

    ;$ End Header
    ;___________________________________________________________________________________________________________|
    ___________________________________________________________________________________________________________|
    ;
    ; Command Line Functions
    ;___________________________________________________________________________________________________________|
    ;
    ; Command Line Function to display Hello World Dialog
    ;___________________________________________________________________________________________________________|

    (defun HW ()(C:HelloWorld))

    (defun C:HelloWorld ()(DialogAlertHelloWorld))

    ;___________________________________________________________________________________________________________|
    ;
    ; Function to display Hello World Dialog in Alert Dialog Box
    ;___________________________________________________________________________________________________________|

    (defun DialogAlertHelloWorld ()(Alert "Hello World"))

    ;___________________________________________________________________________________________________________|
    ;___________________________________________________________________________________________________________|

    (princ "!")
    (vl-load-com)

[peter]

Creating headers is a very professional way of starting a file.

The nice thing is they are mostly cut and paste or create from template notepad file.

What else would you all suggest the header include?

Who, what where, when, why, how much etc...

P=

[tedg]

Creating headers is a very professional way of starting a file.

The nice thing is they are mostly cut and paste or create from template notepad file.

What else would you all suggest the header include?

Who, what where, when, why, how much etc...

P=

Thanks Peter, this is going to be very valuable.

What about revision descriptions and dates, I've done them before but would like your take on the best way and place to put that.
ie:

;; 2017-06-29 Added Error Trapping, Ted G.

[peter]

I would put the revision information directly under the abstract.

I would also create an archive folder and place a copy of the old version inn that folder with a date prefix like 20170629A_MyLispFile.lsp.

Or name it to the version number V001_MyLispFile.lsp

Like AutoCAD it is good to date the release instead of versioning, that way you know when the file was created just by looking at the name.

Lots of ways to do this but thanks for the comment.

Are there any other comments?

[dgorsman]

I locate detailed function descriptions at the functions themselves, rather than at the top. Less scrolling needed for comparison and updates.

For the odd time I create an "execute on load" file (with function calls outside of any defun) I put in a big, capitalized header up at the top.

[peter]

OK that is a valid way of doing it.

I have been trying to create header files that I read and can search from a program.

I like having a list of functions at the top of the file so I can review what is in the file quickly and the syntax for each function

Most professional programmers create .h files to go with their compiled routines.

It is easy to have a routine read down through on of my headers until it finds the

;$ End Header

and export it to a .h file

That is why I chose this way of doing it.

The most important thing about programming is being consistent. If that is your preferred way of documenting your files, just be consistent.

I also try to make it so another competent programmer could easily figure out and maintain my code. (That is not easy)

P=

[Tom Beauford]

Obviously you wouldn't want someone else to profit off the code you created. Can you explain the limits you intend for "Any use by unauthorized person or business is strictly prohibited."?
The code I create & collect is shared with two coworkers in a small office for example. All code from others has the author's header if provided or I'll add one including the author, description, and the link I found it at.
Just want to be sure we're OK.

[Tom Beauford]

I'll get some use out of LISPFunctions.lsp, but VLA-GET-* returned to many. VLA-GET-TEXT*, and VLA-GET-*STYLE were interesting.

[peter]

Obviously you wouldn't want someone else to profit off the code you created. Can you explain the limits you intend for "Any use by unauthorized person or business is strictly prohibited."?
The code I create & collect is shared with two coworkers in a small office for example. All code from others has the author's header if provided or I'll add one including the author, description, and the link I found it at.
Just want to be sure we're OK.

That is just standard language that protects the code from someone else copyrighting it.

I share it here for you all to study and create your own versions of it.

P=

[dgorsman]

OK that is a valid way of doing it.

I have been trying to create header files that I read and can search from a program.

I like having a list of functions at the top of the file so I can review what is in the file quickly and the syntax for each function

Most professional programmers create .h files to go with their compiled routines.

It is easy to have a routine read down through on of my headers until it finds the

;$ End Header

and export it to a .h file

That is why I chose this way of doing it.

The most important thing about programming is being consistent. If that is your preferred way of documenting your files, just be consistent.

I also try to make it so another competent programmer could easily figure out and maintain my code. (That is not easy)

P=

I put a smaller summary of major functions up top, listed by command-line (if any) and interface (main functions to call). Support functions which shouldn't technically get called elsewhere don't get mentioned at the top but still get the standard header at their location in the file.

At one point I was considering a standardized, code-readable header structure to better control auto-loading of support files. I put that aside in favor of loading by library folders.