Hello epic team!
I’m relatively new member here, few weeks, I like the engine a lot, C++ code / engine API design seems to be well designed, I like it, and I’m definitely taking a road to learn hell out of it.
My C++ programming knowledge is based on standard libraries and Windows API which is so well documented that you never really need to looks at code, every possible class and function is perfectly documented on cppreferenceand msdn.
In the case of unreal engine so far I learned that one can’t use online documentation which covers less than 1% of the code and few tutorials.
I figured out the the engine code it self is the best documentation.
and to learn UE code one seriously needs to start reading engine code from ground up, it takes practice for me because I never worked with 3rd party libraries too much because I never needed them.
So I started to read code and stumbled upon funny comments, no comments at all or non informative comments in a lot of headers and sources.
here is an example from Package.h
/**
* A package.
*/
PRAGMA_DISABLE_DEPRECATION_WARNINGS // Required for auto-generated functions referencing PackageFlags
class COREUOBJECT_API UPackage : public UObject
{
...
As you can see the author of the class has put a comment to summarize what is the purpose of this class, and the comment says this class is “A Package”
Seriously?? “A Package”?, as if I couldn’t figure that out my self from class typename.
ok, another example:
/**
* Low level implementation of UObject, should not be used directly in game code
*/
class COREUOBJECT_API UObjectBase
{
friend class UObjectBaseUtility;
here is somewhat more information, it tells us that we should not use it and that it’s a low level implementation.
now the true problem here is that you can’t tell immediately what this class is about, what it does what what it’s purpose is etc…, one needs to read function comments and look at every function code implementation to figure out what is the true purpose of this class, this takes a lot of time. and yes I don’t feel good unless I understand the details as much as possible.
To understand what the classes do one really needs to dive deep, at least 10 minutes per class, just figure out it’s purpose, and there are thousands of classes!
function comments are mostly better almost everywhere, but still not good enough, one still needs to looks as implementation of the function to reveal what it does.
So in general comments are last resort for a user to learn something rapidly and even that is lacking 
I reconciled with that Unreal engine online documentation does not exist, community isn’t big enough to get all the answers I might have, and that I need to parse code in my head to learn, but the lack of explanatory comments for classes is a serious problem for such a big project.
at least 3 lines of comments for function
at least 10 lines of comments for classes
would definitely do a trick!