Hey, everybody!
I'll first answer all of your questions and suggestions and then will share some thoughts that might provide some useful insights during this effort to describe TFS.
Hello
@Fox Rother,
In my opinion, I'd say you are right: members interested in contributing to TFS may find it difficult to start off doing so because of the scope of this project. That's one of the reasons I decided to become a content editor, to share my knowledge (and learn in the process).
. . .
Hello there
@Magich!
Thank you for your input!
What I'm currently doing is to comment everything in
otserv.cpp
and all the critical, immediately used classes and functions around it (tasks, scheduler, databasemanager and game are where I'm focusing).
The comments are not following any standard as of now, I'm just concerned with how to explain what they do and how they do it.
From what I've been seeing, there is
a lot of implicit context in C++ that simply can't be understood by newcomers at first exposure.
As
@Znote said, it's probably best to follow something like VC Doc Tags. In a nutshell, however, I'm really just trying to explain it to myself (which I think to be a good parameter to "newcomer").
I can only see positivity coming with having well-written comments in the sources.
It's a good suggestion. Although for me, the question would rather be — who's willing to take their time to do so? And how many are actually capable
. . .
Hey
@Kaspar!
Thank you for sharing your thoughts!
I totally agree on the questions you're posing.
I for one am greatly interested in commenting for the tons of knowledge that can be acquired from it. It's the greatest example ever, even if it's a bit dense or foggy in some places.
As it's not realistic to expect that from more experienced developers, I propose that we focus on the more fundamental parts and set up a kind of "comment review" process, that would ease some of the tension on the busy, experienced developers.
The source code should follow a standard though, like the
Visual C++ Documentation Tags
But, its a massive job. I think there are well over a thousand functions?
And to build proper comments, you need good understanding of what
. . .
Hey there
@Znote
Thank you for exposing your insights!
Yes, it would be important to follow a standard at some point and VC Doc Tags look awesome. And the earlier, the better!
However, I think
some comment is better than
no comment, specially if we take into account that, as you put it, not many C++ masters would like to read real old functions. x.x
Also, I agree that documenting every single function is not realistic at all. What I meant is that we should document, at least, the foundations.
Most of the tiny little functions (on game, for instance) are pretty self explanatory and build on the other critical subsystems (dispatcher, scheduler, etc).
And yeah! I think that it would certainly boost Lua documentation as well!
Okay, now I'll share some related thoughts hehe
I might be wrong, but I've never seen one single post, either here or at OTFans, XTibia, OTServBR or any other large Open Tibia forum, detailing TFS (or any other project) innerworkings.
Not one single diagram.
This looks like a very serious red flag, because it means the understanding of this system is scattered among very few experts. Should they get absent, the project gets in jeopardy... Also, a system that is not easily understood is a system that is not easily enhanced. There's the contributors aspect as well, but I think we agree we have discussed it in reasonable lengths already. xD
This effort on documenting would expose the "core philosophies" and strategies being applied to TFS, which in turn would, ironically, minimize the number of things that need to be documented (since there is a logic to them!).
We could also see inconsistencies more easily and effortlessly adapt them to those "core philosophies". It'd be easier to review the project as whole and better decide where our efforts should go.
I really think this project
deserves being better understood, better structured and better recognized (by the community and outside of it).
There is almost two decades of hard working into it
So that was my input on your great input! Keep 'em coming, please!
Thanks