| Re: Comments on Coding Style [message #70668] |
Thu, 29 April 2010 13:59  |
David Fanning
Messages: 11724
Registered: August 2001
|
Senior Member |
|
|
Mike Galloy writes:
>>> Also, using one of the standard formats allows the Workbench to show
>>> the help for the routine.
>>
>> How is this done?
>
> Nothing needs to be done to turn it on, just write the comments in
> IDLdoc's rst format.
But how is this accessed from the Workbench?
Cheers,
David
--
David Fanning, Ph.D.
Fanning Software Consulting, Inc.
Coyote's Guide to IDL Programming: http://www.dfanning.com/
Sepore ma de ni thue. ("Perhaps thos speakest truth.")
|
|
|
|
|
|
| Re: Comments on Coding Style [message #70670 is a reply to message #70669] |
Thu, 29 April 2010 13:17  |
Aram Panasenco
Messages: 41
Registered: April 2010
|
Member |
|
|
pp wrote:
> On Apr 29, 4:26 pm, Aram Panasenco<panasencoa...@gmail.com> wrote:
>> I am going to try and use only one header per class that will describe
>> the entire class interface. I am using non-standard tags (Name, Design
>> Details, Abstraction, Syntax, and Public Methods) instead of the more
>> standard (Name, Purpose, Category, Superclasses, Subclasses, Syntax). Is
>> that a bad change? What would you like to see different about the header?
>
> If you use one of the standard formats (and tags) for the comments,
> then you can use IDLdoc to generate nice documentation pages (which
> include very useful features like links and search). If you are not
> familiar with it, see
>
> http://idldoc.idldev.com/
>
> Also, using one of the standard formats allows the Workbench to show
> the help for the routine.
Actually, I have just explored more of IDLdoc and I think it has some
pretty good standards. Maybe I will switch to documenting each routine
by them. I will see. Thanks again for the info!
~Aram Panasenco
|
|
|
|
| Re: Comments on Coding Style [message #70671 is a reply to message #70670] |
Thu, 29 April 2010 13:10 |
Aram Panasenco
Messages: 41
Registered: April 2010
|
Member |
|
|
pp wrote:
> On Apr 29, 4:26 pm, Aram Panasenco<panasencoa...@gmail.com> wrote:
>> I am going to try and use only one header per class that will describe
>> the entire class interface. I am using non-standard tags (Name, Design
>> Details, Abstraction, Syntax, and Public Methods) instead of the more
>> standard (Name, Purpose, Category, Superclasses, Subclasses, Syntax). Is
>> that a bad change? What would you like to see different about the header?
>
> If you use one of the standard formats (and tags) for the comments,
> then you can use IDLdoc to generate nice documentation pages (which
> include very useful features like links and search). If you are not
> familiar with it, see
>
> http://idldoc.idldev.com/
>
> Also, using one of the standard formats allows the Workbench to show
> the help for the routine.
I have just checked out IDLdoc and... wow! I am downright speechless. It
does generate amazing help pages. I am sure there is a way to fine-tune
it (or downright modify the source code) to work with nonstandard tags,
though. Right now, human readability is a bigger concern for me.
~Aram Panasenco
|
|
|
|
|
|
| Re: Comments on Coding Style [message #70674 is a reply to message #70673] |
Thu, 29 April 2010 12:38 |
penteado
Messages: 866
Registered: February 2018
|
Senior Member
Administrator |
|
|
On Apr 29, 4:26 pm, Aram Panasenco <panasencoa...@gmail.com> wrote:
> I am going to try and use only one header per class that will describe
> the entire class interface. I am using non-standard tags (Name, Design
> Details, Abstraction, Syntax, and Public Methods) instead of the more
> standard (Name, Purpose, Category, Superclasses, Subclasses, Syntax). Is
> that a bad change? What would you like to see different about the header?
If you use one of the standard formats (and tags) for the comments,
then you can use IDLdoc to generate nice documentation pages (which
include very useful features like links and search). If you are not
familiar with it, see
http://idldoc.idldev.com/
Also, using one of the standard formats allows the Workbench to show
the help for the routine.
|
|
|
|
| Re: Comments on Coding Style [message #70675 is a reply to message #70674] |
Thu, 29 April 2010 12:26 |
Aram Panasenco
Messages: 41
Registered: April 2010
|
Member |
|
|
David Fanning wrote:
> Aram Panasenco writes:
>
>> I want your comments on the programming conventions I use and how I can
>> change them to make the code more clear and desirable for other
>> programmers to improve. Some things to consider:
>>
>> - Should I use comments or is the code (so far) pretty self-explanatory?
>> - Is the non-standard capitalization annoying you? Should I switch to
>> the classic IDL capitalization (All-caps for IDL keywords, capitalized
>> function and procedure names)?
>> - Is there anything wrong with the way I handle the IDL class? The
>> routines?
>> - Anything wrong at all? I'd rather fix it now than thousands of lines
>> of code later.
>
> I like the style, but, yes, you need comments. Lots of
> them. :-)
>
> Also, the __DEFINE method has to be the *last* method
> in the file, not the first, or you will spend all your
> programming time compiling files as if you were programming
> in C or something. :-)
>
> http://www.dfanning.com/tips/namefiles.html
>
> Cheers,
>
> David
>
>
>
Thank you Maarten and David for your comments ;)
I have followed your advice and added comments, added a header, and
moved the __DEFINE method to the bottom of the file. That means I am now
going to need more criticism about these things.
I am going to try and use only one header per class that will describe
the entire class interface. I am using non-standard tags (Name, Design
Details, Abstraction, Syntax, and Public Methods) instead of the more
standard (Name, Purpose, Category, Superclasses, Subclasses, Syntax). Is
that a bad change? What would you like to see different about the header?
Are the comments describing the intention of the code rather than
repeating it? Are the comments distracting, are there too many or too
little?
Class:
http://pastebin.com/QuNuMKwu
|
|
|
|
| Re: Comments on Coding Style [message #70684 is a reply to message #70675] |
Thu, 29 April 2010 06:05 |
David Fanning
Messages: 11724
Registered: August 2001
|
Senior Member |
|
|
Aram Panasenco writes:
> I want your comments on the programming conventions I use and how I can
> change them to make the code more clear and desirable for other
> programmers to improve. Some things to consider:
>
> - Should I use comments or is the code (so far) pretty self-explanatory?
> - Is the non-standard capitalization annoying you? Should I switch to
> the classic IDL capitalization (All-caps for IDL keywords, capitalized
> function and procedure names)?
> - Is there anything wrong with the way I handle the IDL class? The
> routines?
> - Anything wrong at all? I'd rather fix it now than thousands of lines
> of code later.
I like the style, but, yes, you need comments. Lots of
them. :-)
Also, the __DEFINE method has to be the *last* method
in the file, not the first, or you will spend all your
programming time compiling files as if you were programming
in C or something. :-)
http://www.dfanning.com/tips/namefiles.html
Cheers,
David
--
David Fanning, Ph.D.
Fanning Software Consulting, Inc.
Coyote's Guide to IDL Programming: http://www.dfanning.com/
Sepore ma de ni thui. ("Perhaps thou speakest truth.")
|
|
|
|
|
|
|
|
| Re: Comments on Coding Style [message #70767 is a reply to message #70668] |
Thu, 29 April 2010 14:17 |
Michael Galloy
Messages: 1114
Registered: April 2006
|
Senior Member |
|
|
On 4/29/10 2:59 PM, David Fanning wrote:
> Mike Galloy writes:
>
>>>> Also, using one of the standard formats allows the Workbench to show
>>>> the help for the routine.
>>>
>>> How is this done?
>>
>> Nothing needs to be done to turn it on, just write the comments in
>> IDLdoc's rst format.
>
> But how is this accessed from the Workbench?
Ah, just mouse over a call to a routine in the editor. I see something like:
http://michaelgalloy.com/wp-content/uploads/2010/04/vis_conv ert_mouseover.png
VIS_CONVERT has a header like:
;+
; Use ImageMagick to convert a file between formats.
;
; :Params:
; basename : in, optional, type=string
; basename of file to convert (used for output name as well)
;
; :Keywords:
; density : in, optional, type=long, default=300
; density of output image in dots per inch
; scale : in, optional, type=long, default=100
; scale percentage to use
; from_extension : in, optional, type=string
; extension to use for input file
; from_eps : in, optional, type=boolean
; if set, indicates the input is a Encapsulated PostScript file
; from_png : in, optional, type=boolean
; if set, indicates the input is a PNG file
; from_ps : in, optional, type=boolean
; if set, indicates the input is a PostScript file
; max_dimensions : in, optional, type=lonarr(2)
; maximum dimensions for the output image in pixels
; to_extension : in, optional, type=string
; extension to use for output file
; to_eps : in, optional, type=boolean
; if set, indicates the output should a Encapsulated Postscript file
; to_png : in, optional, type=boolean
; if set, indicates the output should a PNG image file
; to_ps : in, optional, type=boolean
; if set, indicates the output should a Postscript file
; command : out, optional, type=string
; convert command
; output : out, optional, type=bytarr
; output image if output format is an image type
; convert_location : in, optional, type=string
; location of the convert command
;-
pro vis_convert, basename, $
density=density, $
max_dimensions=maxDimensions, $
scale=scale, $
from_extension=fromExtension, $
from_eps=fromEps, $
from_png=fromPng, $
from_ps=fromPs, $
to_extension=toExtension, $
to_eps=toEps, $
to_png=toPng, $
to_ps=toPs, $
command=cmd, $
output=output, $
convert_location=convertLocation
Mike
--
www.michaelgalloy.com
Research Mathematician
Tech-X Corporation
|
|
|
|
comp.lang.idl-pvwave archive
Members
Search
Help
Login
Home
