Meta-discussion — How to present scripts?

[Marco]

Hi all,
I was thinking that it could be nice if we could agree on a general form to present our scripts. Changing field, this is a mandatory practice in the scientific research field, every article has a structure like abstract>intro>exp. section>results & discussion>conclusion>acknowledgments>references. This helps finding the required info because the structure matches the expectation and it's agreed upon universally.
More than once in the past people asked my "why this line does this" and my answer was "read the OP, everything is written there". Sure, long posts trigger a TL;DR reaction, that's why a lil structure may be needed. And believe me, scientific articles can be long bitches.

This is the raw code I use, but other's opinion can be great if the resulting changes make it more commonly acceptable.

Subject

Code: Select all

Script name — Rev. xx.yy / yyyy/mm/dd

Message body

Code: Select all

[size=85][i][This first post gets updated from time to time, particularly when a new revision is released. You are strongly advised to read this post carefully!][/i][/size]

[pre][b]Latest release notes[/b][/pre]
[code]
Rev. xx.yy / yyyy/mm/dd
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

A brief abstract.

Features

✔ Citius: lorem ipsum dolor sit amet, consectetur adipiscing elit.
✔ Altius: lorem ipsum dolor sit amet, consectetur adipiscing elit.
✔ Fortius: lorem ipsum dolor sit amet, consectetur adipiscing elit.

General structure

A section where you can describe how the script is organized: subscripts, initialize/terminate, whatever. Something for the techies, but that should shed some "theoretical" light.
Because if you know how it works you know what you should expect when using it.

• Section A: something.
• Section B: something else.
• Subscript: a little routine on its own.

Usage

A section for the dirty work! Describe the various steps, the clicks and the windows.

Tested on

* Microsoft® Windows® 7 Ultimate SP1 x64 ITA
* Mac OS X 10.8.9.9.9 Growl ENG

Requirements

+ XYplorer (version 12.10.0000 or greater) with
- scripting enabled
- permanent variables enabled
+ Internet connection
+ (suggested) a NTFS partition

Notes

I absolutely take no responsibility for whatever damage, direct or indirect, the usage of this script may cause. This code is provided as-is, use at your own risk. You are advised.

Another warning because it looks good. With an interline to make it stand out.

* A smallish post scriptum.
* A little note: vivamus fermentum semper porta. Nunc diam velit, adipiscing ut tristique vitae, sagittis vel odio. Maecenas convallis ullamcorper ultricies.
* And a bottom line from Shakespeare.

Possible future updates

* Bah;
* Beh;
* Buh(?);

Previous releases notes

Code: Select all

Rev. xx.yy / yyyy/mm/dd
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

Rev. xx.yy / yyyy/mm/dd
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

    Special thanks to...

* Freddie Mercury, for his great voice
* Don, just pro forma tho lol

Code

Code: Select all

 makecoffee;

[/code]
---

Result - check below

---

[This first post gets updated from time to time, particularly when a new revision is released. You are strongly advised to read this post carefully!]

Latest release notes

Code: Select all

Rev. xx.yy / yyyy/mm/dd
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

A brief abstract.

Features

✔ Citius: lorem ipsum dolor sit amet, consectetur adipiscing elit.
✔ Altius: lorem ipsum dolor sit amet, consectetur adipiscing elit.
✔ Fortius: lorem ipsum dolor sit amet, consectetur adipiscing elit.

General structure

A section where you can describe how the script is organized: subscripts, initialize/terminate, whatever. Something for the techies, but that should shed some "theoretical" light.
Because if you know how it works you know what you should expect when using it.

• Section A: something.
• Section B: something else.
• Subscript: a little routine on its own.

Usage

A section for the dirty work! Describe the various steps, the clicks and the windows.

Tested on

* Microsoft® Windows® 7 Ultimate SP1 x64 ITA
* Mac OS X 10.8.9.9.9 Growl ENG

Requirements

+ XYplorer (version 12.10.0000 or greater) with
- scripting enabled
- permanent variables enabled
+ Internet connection
+ (suggested) a NTFS partition

Notes

I absolutely take no responsibility for whatever damage, direct or indirect, the usage of this script may cause. This code is provided as-is, use at your own risk. You are advised.

Another warning because it looks good. With an interline to make it stand out.

* A smallish post scriptum.
* A little note: vivamus fermentum semper porta. Nunc diam velit, adipiscing ut tristique vitae, sagittis vel odio. Maecenas convallis ullamcorper ultricies.
* And a bottom line from Shakespeare.

Possible future updates

* Bah;
* Beh;
* Buh(?);

Previous releases notes

Code: Select all

Rev. xx.yy / yyyy/mm/dd
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

Rev. xx.yy / yyyy/mm/dd
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.
   Donec a diam lectus. Sed sit amet ipsum mauris.

    Special thanks to...

* Freddie Mercury, for his great voice
* Don, just pro forma tho lol

Code

Code: Select all

 makecoffee;

[TheQwerty]

Great idea to make posting scripts in the forum a better experience for everyone!

I haven't looked it over extensively but I have one quick suggestion; move all emoticons outside of the text formatting tags.

For example:

Code: Select all

 :!:  :!:  :!: [b][u]I absolutely...[/u][/b]

I absolutely...

Instead of:

Code: Select all

[b][u] :!:  :!:  :!: I absolutely...[/u][/b]

I absolutely...


EDIT: I also think it might look better if the headers were both bold and underlined.

[highend]

Great idea per se, but I have one major problem with it: It takes more time to do the documentation than coding the script

Ofc, documentation is always good (and time consuming) and necessary if you earn money from it but I don't know if this would be a bit of overkill. Apart from the problem that not all the people that post scripts on this forum will use your template...

Apart from that: Thanks for taking the time to create this one!

[Marco]

@TheQwerty
Will look into those, thanks.

@highend
Yes, it takes time, but not as much as you think, once a good template is defined. Nobody expects all this for a quick two-line, but when code begins to be complex and does complex things, documentation it's important. There might be notes, incompatibilities, little suggestions, and so on, that are hard to track when scattered along a multipage thread.
Knowing what a script does, and when and where was changed, should be essential.
I'm just suggesting a template that, imo, has all the sections that may be required.