Readmes or massive comments? What's your preference? - Printable Version+- Save-Point (https://www.save-point.org)
+-- Forum: Games Development (https://www.save-point.org/forum-4.html)
+--- Forum: Development Discussion (https://www.save-point.org/forum-17.html)
+--- Thread:
Readmes or massive comments? What's your preference? (/thread-2921.html)Readmes or massive comments? What's your preference? - PK8 - 05-14-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?
Readmes or massive comments? What's your preference? - EJlol - 05-14-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.
Readmes or massive comments? What's your preference? - MicKo - 05-14-2009
I prefer having the comments where I need them. Like EJlol said, basically.
Readmes or massive comments? What's your preference? - Yin - 05-15-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.
Readmes or massive comments? What's your preference? - DerVVulfman - 05-15-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.
Readmes or massive comments? What's your preference? - EJlol - 05-15-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.
Readmes or massive comments? What's your preference? - Kain Nobel - 05-25-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!"
Readmes or massive comments? What's your preference? - EJlol - 05-25-2009
Kain Nobel Wrote: ...as ReadMe files take up space on my harddrive...so do comments :P
Readmes or massive comments? What's your preference? - Charlie Fleed - 05-25-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.
Readmes or massive comments? What's your preference? - Asi - 06-22-2009
if you go with readme you should save in .txt not everyone has a fancy text editor^-^
-Asi