Save-Point
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)

Pages: 1 2 3


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