Experimental Physics and
Industrial Control System

"Gurd, Pamela A." <[email protected]> · Fri, 08 Sep 2006 13:15:08 -0400

A few short comments telling what a page of code does - are helpful (if,
of course, they're kept up-to-date) - but too many comments do make it
harder to read the code.  Too much detail almost guarantees that the
comments will not match what the code actually does.

Self-evident comments (like calling a function convert2number, and a
comment saying "call the convert2number function") ... those drive me
crazy.

   Pam.

> -----Original Message-----
> From: Dalesio, Leo `Bob` [mailto:[email protected]]
> Sent: Friday, September 08, 2006 12:45 PM
> To: David Dudley; [email protected]
> Subject: RE: EPICS source Documentation - Bloviation inside - don't
open
> unless you want to waste the time
> 
> 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