Experimental Physics and Industrial Control System
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.
- References:
- RE: EPICS source Documentation David Dudley
- Navigate by Date:
- Prev:
RE: EPICS source Documentation David Dudley
- Next:
Re: EPICS source Documentation Andrew Johnson
- Index:
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
<2006>
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
- Navigate by Thread:
- Prev:
RE: EPICS source Documentation David Dudley
- Next:
Re: EPICS source Documentation Andrew Johnson
- Index:
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
<2006>
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024