Re: EPICS source Documentation

[Paul Joireman <joireman@fnal.gov>]

As is clear from the different views regarding comments, it is ultimately up to individual programmers to write comments.  Their use of comments depends upon training, internal and external standards, experience-ability and perspective on comments many of which can be lumped into the category of how they go about doing their work.  Since it would be hard to find two people who work in exactly the same way, the use of comments will vary widely for a large project like EPICS with many developers, assuming the lack of a formalized and enforced "standard" regarding comments.   At the risk of sounding obvious, no one method works for all.

I write and appreciate comments describing functions, which give a general outline of the implementation, usage, warnings and references.   I also find comments within a function describing a block of code to be helpful in understanding what is happening and quickly determining where things need to be modified.    The longer the function the greater the need for good comments to guide the maintainer, one reason, among many, that experts advocate functions be no longer than a single page of paper.      Comments internal to a function will ultimately depend upon how the function is written and could be eliminated by making the code as self-documenting as possible, as Andrew advocates, with good variable and function names so the meaning is clear.

As Bob has pointed out comments are not executed and add the additional cost of "comment maintenance" to that of code maintenance.   Ultimately the source code detemines what happens in the program, the syntax provides a fixed language which all developers must obey due to the language standard which is enforced by compiler.    Commenting "standards" vary across organizations and individuals and are for the most part unenforced.

I believe there is semantic value in the text provided by comments, especially when trying to understand a large codebase.   Prose text is always more readable that source code.   I have also benefitted greatly from the use of source code comments which can be extracted and formatted as a set of linked HTML pages, using doxygen or javadoc, as Kay points out.   When I read through code I often find myself writing or clarifying comments so that my future self (6 months  or even 2 weeks later)  will easily recognize what is happening or what I meant to do.
However, these are my work habits and will not necessarily work for everyone, nor should they have to.  

Paul

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 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?

David Dudley

  

BEGIN:VCARD
VERSION:2.1
X-GWTYPE:USER
FN:David Dudley
TEL;WORK:880-3740
ORG:;MIS
TEL;PREF;FAX:880-3741
EMAIL;WORK;PREF;NGW:DavidDu@cctexas.com
N:Dudley;David
END:VCARD