Download

Engine C++ code comments

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 :frowning:

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!

Comments only for key classes and functions. I truly hate when there’s more comments than actually code. Also, the comments in these 2 examples are more than enough. At least that’s what I think.

Can you please now briefly describe what is the purpose of **UPackage **class and what it does without looking at where and how it is being used?
You said the comment is enough so you should be able to do so.

Well, I would assume that the package class means … it’s a package. The same way a UObject is a UObject. I really don’t understand what the problem is? Never used the class, but by the name and members like AccessThumbnailMap() e IsFullyLoaded(), I would assume it most likely refers to an unreal file package.

Now, in relation on where and how is being used, well, based on my assumption, I would said thats rather clear, right? You create, load, save, delete … packages containig textures, sounds, and so on. Therefore UPackage should also be a serializable class.

Sometimes the normal documentation, as opposed to the API, has the answers you’re looking for in terms of top-level understanding of core classes. For example, for UObject (which is one of the most important base classes in the entire code base), check this out: https://docs.unrealengine.com/en-US/Programming/UnrealArchitecture/Objects/index.html

I think you guys didn’t understand me, yes everybody knows what UObject and similar key classes do, I just gave an example, but’s that’s only a tiny portion, online documentation covers only 1% of the code.unless you’re just having fun with UE this is not even close to enough.

If online documentation is lacking no problem, but at least code should be commented then (or vice versa) leave comments as they are but start building online documentation.

I’m sure epic staff will say that UE is huge code base and it would take too much effort to document everything, but that’s no excuse! why didn’t you document from the very start so you would not have this problem?

When people start learning C++ one of the very first thing a teacher will tell them to make sure to comment their code because other people might read it. that’s very basic programming skill.

We understand.

My criticism was not against comments in general, but against unnecessary comments that in the end helps virtually nothing to the understanting and to the correct usage of the code.

We all agree that there’s a real lack of both documentation and comments.

I would also like to point out that the UE4 code base is based on the UE3 code which is build on UE2 and which was based on UE1. It is very old code.