Readmes or massive comments? What's your preference?
#1
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?
Reply }
#2
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.
Reply }
#3
I prefer having the comments where I need them. Like EJlol said, basically.
Reply }
#4
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.
Reply }
#5
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.
Reply }
#6
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.
Reply }
#7
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!"
[Image: Button-BOTB.png]
[Image: Save-Point.gif][Image: Button-You-Tube2.png][Image: Button-Sound-Cloud2.png][Image: Button-Audio-Mack2.png]
[Image: LS-Banner.gif]
NEW ALBUM OUT NOW!

Reply }
#8
Kain Nobel Wrote: ...as ReadMe files take up space on my harddrive...
so do comments :P
Reply }
#9
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.
Reply }
#10
if you go with readme you should save in .txt not everyone has a fancy text editor^-^

-Asi
Reply }


Possibly Related Threads…
Thread Author Replies Views Last Post
  Text files, HTML pages or giant comment blocks? What's the end-user's preference? PK8 3 7,011 06-29-2011, 01:21 PM
Last Post: Kain Nobel



Users browsing this thread: 1 Guest(s)