Drafters Forum | JOBS | Drafting Standards | Funnies | Technical Dictionary | AutoCAD Tutorials | Free Lisp | Free Blocks

ARTICLE: Top ways drafters can make money online with Freelancer.com

AutoLISP Lesson 3 - COMMENTS

From Draftsperson.net

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

More Lessons


Need drafting work?

We are having great success with Freelancer.com. With this website we can win all types of drafting work. People from all over the world are looking for freelancers skilled in AutoCAD, Revit, Civil 3D and Microstation, are you one of those people? If so you can live the freelancer lifestyle! and work from any location you want too. Freelancer.com, it works really well - we like it - and we believe you will too.

Looking for CAD drafters?

With modern construction, software and increased legal requirements, we often require specialized assistance with our projects. Putting skilled staff on full time is not always economically feasible for small businesses. Freelancer.com solves this problem. On this website you can engage skilled drafters. Either on fixed prices for specific tasks, or reasonably priced hourly rates for longer term contracts.

E-book: AutoCAD Block Best Practices

We draw repetitively when using AutoCAD. If we manage the drawing elements as reusable contents, it will increase our productivity significantly. Not only can we draw faster, we can add information to our blocks. Which allows us to generate useful reports. This is what Edwins e-book entitled AutoCAD Block Best Practices is all about. Yes, increase your productivity with the block!



Printable version

Toolbox

Views

Main Page | Free AutoCAD Blocks | Free Revit Families | Funnies | Drafting Standards | Drafting & CAD Forums | Structural Drafting | Technical Dictionary

Personal tools

MediaWiki