| Re: Looking for IDL code documentation standards [message #44048] |
Tue, 17 May 2005 07:13  |
Antonio Santiago
Messages: 201
Registered: February 2004
|
Senior Member |
|
|
Ken Mankoff wrote:
>
> On Tue, 17 May 2005, Ben Panter wrote:
>
>> JD Smith wrote:
>>
>>> I whipped up this example coding standard, trivially enforceable by
>>> IDLWAVE:
>>>
>>> http://idlwave.org/idlwave_template.pro.html
>>
>>
>> Slightly at a tangent, but how did you produce the syntax highlighted
>> html? I'd thought of running the colour postscript output of IDLWAVE
>> through some sort of ps->html conversion but never got any further. Is
>> there already some software out there to do this?
>
>
> I use this to generate pretty-print PS files. I think a2ps can also be
> used to generate HTML.
>
> a2ps --pre=idl --pro=color foo.pro
>
> There is also a pretty-print-buffer command in emacs.
>
> -k.
>
I use htmlize-buffer (http://fly.srk.fer.hr/~hniksic/emacs/htmlize.el)
with color-themes.
--
-----------------------------------------------------
Antonio Santiago P�rez
( email: santiago<<at>>grahi.upc.edu )
( www: http://www.grahi.upc.edu/santiago )
( www: http://asantiago.blogsite.org )
-----------------------------------------------------
GRAHI - Grup de Recerca Aplicada en Hidrometeorologia
Universitat Polit�cnica de Catalunya
-----------------------------------------------------
|
|
|
|
|
|
|
|
| Re: Looking for IDL code documentation standards [message #44055 is a reply to message #44050] |
Mon, 16 May 2005 13:01  |
Michael Wallace
Messages: 409
Registered: December 2003
|
Senior Member |
|
|
> IDL coding style tends to be quite personal, even for RSI programmers.
> Take a quick perusal through !DIR/lib and notice that they can't even
> agree on whether to indent the body of routines!
Yeah, I've noticed that before. Lack of indentation drives me up the wall.
> I whipped up this example coding standard, trivially enforceable by
> IDLWAVE:
>
> http://idlwave.org/idlwave_template.pro.html
>
> Hope it is of some use.
Actually, except for the indentation rules, it is pretty close to the
rules I made up for myself.
Reserved Words - lowercase (e.g. begin, end, do, for, if, while)
Variables: lowercase, words separated by "_" (e.g. my_var)
Routines: lowercase, words separated by "_" (e.g. my_func)
Keywords: UPPERCASE, words separated by "_" (e.g. MY_KEYWORD)
Classes: MixedCase, no separation character (e.g. MyWonderfulClass)
Methods: MixedCase, no separation character (e.g. GetProperty)
Indentation: 4 spaces for each block
Long lines: 8 spaces or align to previous line (programmer's discretion)
If if...then...else is too long to fit on a single line, break into
begin...end blocks rather than use line continuation. Same rule for
while, for, etc. Simply put, use line continuation only when you have to.
Avoid multi-command lines (e.g. command1 & command2 & command3)
Use spaces around operators (e.g. var = foo + 2 ^ 32)
No spaces between function name and parenthesis (e.g. my_func(foo) )
I've got several more spacing rules, a couple commenting rules and file
naming conventions, but I don't want to spend the time writing them out.
And I'd probably wind up boring everyone to death. Either that or
they'd just stop reading and go on to a thread with more excitement. :-)
-Mike
|
|
|
|
| Re: Looking for IDL code documentation standards [message #44057 is a reply to message #44055] |
Mon, 16 May 2005 12:06 |
JD Smith
Messages: 850
Registered: December 1999
|
Senior Member |
|
|
On Mon, 16 May 2005 12:58:25 -0500, Craig Markwardt wrote:
>
> Michael Wallace <mwallace.no.spam@no.spam.swri.edu.invalid> writes:
>>>> Is there somewhere in the IDL guides or on the web that the IDL code
>>>> documentation standards are located? I've been able to piece together
>>>> some of it from IDL code examples, but I'd like to see a definitive
>>>> guide.
>>> So would I! But, alas, you and I would be the only
>>> ones reading it. :-(
>>
>> I too would be reading it. That makes three of us. I actually asked
>> a very similar question of this newsgroup many moons ago and since
>> then I've gone on to develop my own style so that I'm at least
>> internally consistent within my own code. RSI can't even claim that.
>
> A long-ago contributor, Mark Schienle, once posted a link to his own
> style guide, which may be kind of what you are after. Unfortunately
> his web site, ivsoftware.com, is now defunct.
>
> I use idlwave to enforce indentation, which leads to consistent
> appearance of comments.
>
> I have a documentation template I use, which I could post, but I also
> deviate from my own template :-)
IDL coding style tends to be quite personal, even for RSI programmers.
Take a quick perusal through !DIR/lib and notice that they can't even
agree on whether to indent the body of routines!
I whipped up this example coding standard, trivially enforceable by
IDLWAVE:
http://idlwave.org/idlwave_template.pro.html
Hope it is of some use.
JD
|
|
|
|
|
|
| Re: Looking for IDL code documentation standards [message #44059 is a reply to message #44058] |
Mon, 16 May 2005 10:58 |
Craig Markwardt
Messages: 1869
Registered: November 1996
|
Senior Member |
|
|
Michael Wallace <mwallace.no.spam@no.spam.swri.edu.invalid> writes:
>>> Is there somewhere in the IDL guides or on the web that the IDL code
>>> documentation standards are located? I've been able to piece together
>>> some of it from IDL code examples, but I'd like to see a definitive
>>> guide.
>> So would I! But, alas, you and I would be the only
>> ones reading it. :-(
>
> I too would be reading it. That makes three of us. I actually asked
> a very similar question of this newsgroup many moons ago and since
> then I've gone on to develop my own style so that I'm at least
> internally consistent within my own code. RSI can't even claim that.
A long-ago contributor, Mark Schienle, once posted a link to his own
style guide, which may be kind of what you are after. Unfortunately
his web site, ivsoftware.com, is now defunct.
I use idlwave to enforce indentation, which leads to consistent
appearance of comments.
I have a documentation template I use, which I could post, but I also
deviate from my own template :-)
Craig
--
------------------------------------------------------------ --------------
Craig B. Markwardt, Ph.D. EMAIL: craigmnet@REMOVEcow.physics.wisc.edu
Astrophysics, IDL, Finance, Derivatives | Remove "net" for better response
------------------------------------------------------------ --------------
|
|
|
|
|
|
|
|
| Re: Looking for IDL code documentation standards [message #44142 is a reply to message #44055] |
Tue, 17 May 2005 10:25 |
Timm Weitkamp
Messages: 66
Registered: August 2002
|
Member |
|
|
On 16.05.05 at 15:01 -0500, Michael Wallace wrote:
> Reserved Words - lowercase (e.g. begin, end, do, for, if, while)
>
> Variables: lowercase, words separated by "_" (e.g. my_var)
> Routines: lowercase, words separated by "_" (e.g. my_func)
> Keywords: UPPERCASE, words separated by "_" (e.g. MY_KEYWORD)
>
> Classes: MixedCase, no separation character (e.g. MyWonderfulClass)
> Methods: MixedCase, no separation character (e.g. GetProperty)
I find it useful to distinguish, in my code, names of routines that are
part of the IDL distribution from names of contributed routines. I do this
in the following way:
PRINT, SIN(MyFunc(x))
and apologize to all those who detest the all-uppercase way. What I
advocate is just only to make clear in *some* way that "sin" is part of
the IDL distribution, whereas "myfunc" isn't.
This helps avoid confusion and makes it easier to track down problems
caused by collisions in that small world called namespace.
Cheers,
Timm
--
Timm Weitkamp <http://people.web.psi.ch/weitkamp>
|
|
|
|
| Re: Looking for IDL code documentation standards [message #44143 is a reply to message #44050] |
Tue, 17 May 2005 09:21 |
JD Smith
Messages: 850
Registered: December 1999
|
Senior Member |
|
|
On Tue, 17 May 2005 09:11:12 +0200, Ben Panter wrote:
> JD Smith wrote:
>> <snip>
>> I whipped up this example coding standard, trivially enforceable by
>> IDLWAVE:
>>
>> http://idlwave.org/idlwave_template.pro.html
>>
>> Hope it is of some use.
>
> Slightly at a tangent, but how did you produce the syntax highlighted
> html? I'd thought of running the colour postscript output of IDLWAVE
> through some sort of ps->html conversion but never got any further. Is
> there already some software out there to do this?
Yep, it's called "htmlize", and is pre-shipped with XEmacs (I just loaded
it into GNU Emacs, and it worked fine). M-x htmlize-buffer.
JD
|
|
|
|
|
|
comp.lang.idl-pvwave archive
Members
Search
Help
Login
Home
