Re: EPICS source Documentation

[Andrew Johnson <anj@aps.anl.gov>]

David Dudley wrote:
> Just a strange question, but I've noticed a tendency of all the
> source files to not have any comments (or very few) in them regarding
> what they do.
>
> Is this a standard I've just never known about? Typically, source(s)
> that I compose end up having as much in comments (or more) than in
> code, for the simple reason that I can't concentrate on one component
> at a time, and I might work some now, and some two or three days from
> now (and I've slept between then and now).

I think a lot of it relates to the personal coding style of the original 
author(s) of EPICS Base.  If you look at code from other people such as 
device support modules you'll see more comments.

> I get so busy with the multiple things I have to do, that if I don't
> comment the hell out of what I write, I might have to spend quite a
> bit of time decoding what I was doing before I needed to switch.
>
> Is this the normal style for EPICS, or would there be any objections
> to comments being added to some of the files as I work with/on them?

Personally I'm in favor of including comments where they contribute to 
understanding what the code is trying to accomplish or as a reminder 
that there's something going on here which might not be immediately 
obvious.  I also try to choose routine and variable names that are self 
exdplanatory, since that reduces the number of comments that are needed 
(please don't try and use Hungarian notation in names, even the original 
'sensible' version).

I don't think we're likely to remove any comments from the code you 
submit so don't worry about including comments that you feel are useful.

- Andrew
--
There is considerable overlap between the intelligence of the smartest
bears and the dumbest tourists -- Yosemite National Park Ranger