Fate-Grand-Order_Lua icon indicating copy to clipboard operation
Fate-Grand-Order_Lua copied to clipboard

Clear separataion of "Documentation" and "Code Comment"

Open 29988122 opened this issue 6 years ago • 0 comments

As I've just read a few software engineering books recently...

Code Comment should only address the behavior of the said code block in the limited scope, while Documentation should address things in a greater sense i.e., @potchy drew an image for the refactoring - it belongs to the "Documentation" section in wiki. Interactions between modules and specs of each modules should also be addressed in "Documentation"(if needed, of course. most of the time it's simple enough so we don't have to document them.)

Another example is CE image cropping. I will remove that from readme.md, move it into "Documentation" section. Again, readability.

Also, by reducing the amount of comments in the setting Lua files, we won't have to do minor trival comment changes in the future. Just redirect users to our Documentation - wiki localized readme.md page in this case - to achieve better abstraction on the human language aspect of this project.

We've just done refactoring, and I believe it's the correct timing doing so to eliminate all the hassle in the foreseeable future.

This will not be done very soon, at least not before we've done the most part of the overhaul. So, I just add this issue, put it in project board section for future references.

29988122 avatar Dec 24 '18 06:12 29988122