Readmes or massive comments? What's your preference?
05-25-2009, 07:35 PM
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.
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.