Posts: 1,664
Threads: 391
Joined: May 2009
I'm making this topic because I'm working on a pause script that will have A LOT of features and several that are going to need some explaining.
I was working on a readme in OpenOffice, came by on this site and read a shout by MicKo which kinda inspired this topic. :P
Would you prefer to read a script which is simply just a huge comment block dedicated to explaining everything in a script or would you prefer an external text/word/open office document instead?
Posts: 311
Threads: 16
Joined: May 2009
It really depends on the size, and how much you need to explain for each option. Most of the time I like to see comments in this way:
# comments about option A
option A
# comments about option B
option B
etc.
Posts: 84
Threads: 5
Joined: May 2009
I prefer having the comments where I need them. Like EJlol said, basically.
Posts: 627
Threads: 38
Joined: May 2009
Comments where needed help the user learn scripts themselves. Charlie lee has lots of comments in his script and i know exactly where and how to edit something if I needed it changed. But a big comment block in the beginning is also helpful.
My partner in crime = TREXRELL
Posts: 11,272
Threads: 651
Joined: May 2009
I have been needing to use both. Of course it depends on the script.
For one-pagers, I tend to put all my instructions and junk at the beginning and for larger ones, I may have just one page dedicated to the instructions.
I had to start doing that when people kept losing the instructions or stopped reading the post itself. Other than massive ones where you just KNOW you'll need a manual, many people just hate additional downloads. Even so, there are so many that still don't download the instructions.
Posts: 311
Threads: 16
Joined: May 2009
A good (short) script should be self-explainable, this can be accomplished with using good variable names, not to many options and in case where the user has to add something (hash, array, etc) a few examples.
Ofcourse this doesn't work with very long scripts.
Posts: 937
Threads: 101
Joined: May 2009
I perfer comments too, as ReadMe files take up space on my harddrive and I'm a cheapskate with my 300GB of memory lol. Besides that, ReadMe files are easy to loose.
"Oops, I just emtied my Recycle Bin and the project with the instructions was in it... I forgot how the hell to use this thing!"
Posts: 311
Threads: 16
Joined: May 2009
Kain Nobel Wrote: ...as ReadMe files take up space on my harddrive...
so do comments :P
Posts: 1,128
Threads: 43
Joined: May 2009
I think that both are needed simply because they usually have different intended readers.
A scripter that wants to modify some script or someone who reads scripts for learning will likely need comments throughout the code, while a "pure user" will benefit from a user guide/readme that focuses on how to use the script instead of how it works.
Finally, but this my personal idea, I don't like to find a big readme in form of an initial wall of comment, mainly because a good readme should present the information in a well structured fashion, including tables, pictures, and so on, and a such thing cannot be done with comments only.
Posts: 14
Threads: 2
Joined: Jun 2009
if you go with readme you should save in .txt not everyone has a fancy text editor^-^
-Asi