• There is NO official Otland's Discord server and NO official Otland's server list. The Otland's Staff does not manage any Discord server or server list. Moderators or administrator of any Discord server or server lists have NO connection to the Otland's Staff. Do not get scammed!

[Suggestion] Comments in source files

Fox Rother

Highly Skilled in Noobing
Joined
Aug 10, 2010
Messages
63
Reaction score
35
Hello. 🙃

I feel like the lack* of documentation (aside from the source being C++) is one of the key factors keeping new contributors away
I imagine this observation is not exclusively mine.

I'm not well versed in C++, but I'm learning as fast as I can.
What I can do right now is to comment the source extensively and maybe build on that later on.

I'd like to know if that is considered helpful to the community.

*Perfectly understandable since this project does have a lot of baggage (and was always maintained by a handful of historically pressured maintainers).

Thank you
 
Last edited:
Hello. 🙃

I feel like the lack* of documentation, aside from the source being written in C++, is one of the key factors keeping new contributors away. I imagine this observation is not exclusively mine.
I'd like to know if you share this view and if there's something I could do to help in this regard.

I'm not well versed in C++, but I'm learning as fast as I can. What I can do right now is to comment the source extensively and maybe build on that later on.

*Perfectly understandable since this project does have a lot of baggage (and was always maintained by a handful of historically pressured maintainers).

Thank you

Take a look at this:
 
@hellboy Thank you! Wondering why we don't have a thread in here, too... :p

I'm not really confident to write on TFS internals just yet, that's why I proposed commenting the source agressively as a first step. It'll be good for learning and gathering input as to how to explain TFS Architecture, which even more experienced developers seem to have trouble: it's a rather large and unorganized code base, it's even been described as a spider web (not criticizing, already said I understand why, let's not make it the discussion).
Maybe it's a good thing to have a fresh view (as in learning from scratch) to explain each thing and clear up on what are the most complex mechanisms, or the most confusing concepts, etc.

As to other topics: I surely can contribute on why you need to compile the source, use Linux and so on!
But I'd really like to know the position of the experienced developers on this view. :)
 
Last edited:
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).
I like your idea of commenting the sources, therefore I encourage you to do so ;) It will help you at learning C++ and the community will have a reference of how TFS works without the need of going through the sources.
There's a question though: how do you plan to comment the sources? (What strategy are you going to follow?) 😯

Kind regards,
Magich :D
 
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 of doing so?
 
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? :p And to build proper comments, you need good understanding of what exacly the function does.

Any C++ masters here, who want to not code cool stuff, but read old functions and document them? :p

But it would also help build the Lua docs, since its easier to see what the source code is doing.

C++:
/// <summary>Sorts the list to by the given column</summary>
/// <param name="sel">Column to be sorted (index-1-based) and sort direction (pos. = ascending)</param>
/// <returns>Documentation of return type</returns>
void CExamlist::SetSorting(int sel) { ... }
Gets interpreted by ReSharper C++ to:
j5cst.png
 
Last edited:
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? :p 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! :p


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 o_O

So that was my input on your great input! Keep 'em coming, please! 🤩

Thanks
 
Last edited:
You're full of enthusiasm; you are driven and like to take initiatives — I like that about you.
However, this is not an easy task to be done. Try it out for a bit yourself, and then share some of your commenting for review.
Some one could chirp in and comment about your commenting, perhaps some users will start commenting code themselves, and we could achieve something out of this.
Let's see how it goes!
 
Hey, guys! 🙃

Just passing by to let you know that I didn't give up on 'translating' the sources just yet. :p
College is taking a bit more of my time this week, so I hadn't have the time to be as focused as I wish. :/

I think I figured out the dispatcher and might have something written down this weekend.
I'll then move on to the scheduler and then the service manager/server.

Thanks!
 
This is a great initiative and I fully support it. As you said, some comments are better than no comments at all, so if you are willing to put your work into it, kudos to you, because I am sure it will help people (not even necessarily new contributors) understand the code better.
 
I just wanted to say that I think this was a great initiative! I'm not an experienced programmer, so at least to me your comments were very helpful. Would love to see it in more of the other source files. Any further progress since your last post? :)

I feel like the lack* of documentation (aside from the source being C++) is one of the key factors keeping new contributors away

I also think you're right on the money with this.
 
Back
Top