• Skip to main content
  • Skip to primary sidebar
blog.draftsperson.net

blog.draftsperson.net

the art of technical drawing

blog.draftsperson.net

AutoLISP Lesson 3 – COMMENTS

August 1, 1999 Leave a Comment

(April 1999)
Why comment? In the lifecycle of a program there will be times when it is necessary to make changes, comments should be viewed as a revision and quality control function. Comments should only be written to aid in the later modification of the program or to find out what version of a particular program or function is currently being used. A good comment states something that is not obvious from looking at the code.

Header comments

Header comments are written because it is sometimes difficult to look into a program and get all the information needed to start working on the code. A header comment should take care of providing the following information to any future developer:
  • The title and purpose of the file.
  • Authorship and creation date.
  • Revision history list.
Example:
;; Title: Garden Path
;; Purpose: To draw a garden path for landscape drawings
;; Written: YZ
;; Creation: 2-5-1998
;; Revisions:
;; 10-9-1999 - Fixed arc bug
;; 15-9-1999 - Saved Osmode and restore at end of program

Indenting level comments

Some comments need to be made in the body of the code, these are known as indenting level comments. As you can tell from the name, the indenting level comments should be at the indenting level of the code they are describing.
Most indenting level comments will be a summary description of a function or module. If you are naming function and variables correctly it should not be necessary to do indenting level comments inside a function. If you feel a comment is required, it should explain the WHYS of the code it is commenting rather than HOW it is doing it. The how should be obvious from reading the code.
If you violate good programming style to make something work, you should add a comment to make sure the next programmer understands why you did it that way. A comment can be just a note to the next guy without really explaining the code itself.
You may want to comment control structures if they get to complicated, but if they are too complicated you may also want to rewrite the structure to make it less complex. The better your structural procedures and naming, the less commenting you will need.
Data structures are also a place where commenting can come in handy to explain how you set up the data and why.
The units of numerical data are a good place to have comments. If your program is expecting the units in feet or millimeters, it should state that somewhere. Ranges of allowable numeric values should also be commented so some checking of the incoming data can be accomplished.
Global data variables should be commented as to what and why they exist. If you have named your global variables correctly the comments may be unnecessary, but you should still look at all global variables and be sure they are clear as to why they are global.
If you are commenting a function make sure you document the inputs and outputs to the function. Also you may want to document any revisions to the function. If the routine is short enough it may not be necessary to comment it. Remember that if a comment is not needed it should not be written. Indenting level comments have only one formatting rule.
  • Begin at the current level of indentation and are preceded by two semicolons.
Example:
(defun P-ARRAY ( / n af yn cen c ra )
;; Define number of items in array
(setq n 0)

Summary

Comments should be written as the code is being written. Waiting till the end, when the program is finished is the wrong thing to do. When you are writing the code you will know when a comment is necessary and when it is not. Later you may not be so sure.

Filed Under: AutoCAD Tutorials, AutoLISP Tutorials

Reader Interactions

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Primary Sidebar

Subscribe to our Youtube Channel

Categories

  • American Steel Industry (4)
  • AutoCAD Articles & Reference (24)
  • AutoCAD Bugs & Problems (19)
  • AutoCAD Tips (28)
  • AutoCAD Tutorials (42)
  • AutoLISP Routines (145)
  • AutoLISP Tutorials (15)
  • CAD Standards (6)
  • Civil 3D (7)
  • Civil Drafting (4)
  • Dimensions (2)
  • Drafting Funnies (71)
  • Drafting History (9)
  • Drafting Standards (65)
  • Electrical Drafting (2)
  • General IT reference (10)
  • Geometry (15)
  • GIS (2)
  • Office Life Hacks (1)
  • PT (1)
  • Revit Tutorials (53)
  • Steel Detailing (12)
  • Structural Drafting (23)
  • Technical Dictionary (45)
  • Useful Website Links (19)

Provided for free with no warranty ยท Log in