Messages from Usenet group comp.lang.idl-pvwave, compiled by Paulo Penteado
Re: Looking for IDL code documentation standards
wcramer 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. :-( Cheers, David -- David Fanning, Ph.D. Fanning Software Consulting, Inc. Coyote's Guide to IDL Programming: http://www.dfanning.com/
>> 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. -Mike
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 ------------------------------------------------------------ --------------
Hi Doug, Here's about the closest thing I've ever found... cd to $IDL_DIR and check out: examples/template.pro Best -Tim.
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
> 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
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? Thanks, Ben
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.
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 -----------------------------------------------------
Antonio Santiago wrote: > Ken Mankoff wrote: >> >> 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. > > Thanks guys -- I'll see what I can get with those. Ben
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
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>