Experimental Physics and
Industrial Control System

"Dalesio, Leo `Bob`" <[email protected]> · Fri, 8 Sep 2006 13:30:01 -0700

As the quote is mine - I'll just say that I could not agree more. 

-----Original Message-----
From: David Dudley [mailto:[email protected]] 
Sent: Friday, September 08, 2006 12:54 PM
To: [email protected]
Subject: RE: EPICS source Documentation

I will agree, "... Code always tells the truth.  Comments sometimes do not...".
However, a little comment block here and there, saying something along the line of "... in this block, the code is intended to do <such - and -such...>, that sort of points you in the direction of where you want to go, even if the comment is not 100% direct, would be useful most of the time.

I've seen situations where there will be some involved, intricate, block of code that maybe does a specific function (and perhaps exactly the function I'm looking for), but the functioning of the block might be obscure or embedded in the actual structure of the code.  Having a comment that says "... here the routine is going to open the door..." or something that just gives a pointer to what is going on - obviously can't be entirely bad.  

Just a note on Friday afternoon......

David Dudley

>>> "Dalesio, Leo `Bob`" <[email protected]> 09/08/06 11:45 AM 
>>> >>>
As the question must not be serious -
I'll state the obvious......

Code always tells the truth. Comments sometimes do not.

Documentation says how to use it.
Reading the code tells you how to modify it.

It is good practice for the comments to at least get you to the modules and subroutine that you are looking for. Once inside - you get what you get.

Personally, I write comments for me - I have a short memory.
There are very talented programmers that have done a lot of the base code, that do not trust anything but the code. They would read the code regardless of the presence of comments. They obviously don't need comments.

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System