How to Write CODE That Documents Itself

Stop using comments! In this video you'll learn how to write code that documents itself.

#Programming #GameDevelopment #Unity3d

Programming for game development often requires complex code that can be hard to understand if isn't documented. As a result, many game developers pepper their code with comments that explain exactly what it does, line-by-line.

On the surface, this seems like a good practice. But in reality, highly commented code usually means that it 's poorly written and hard to maintain.

Instead of relying on comments, game developers should learn how to write code that flows easily and documents itself. In this video, I share the simple trick of encapsulation that can take your code from spaghetti to self documented and clean.

My Favorite Unity Assets 💯⤵️

* Disclosure: These are affiliate links, which means I'll receive a commission if you use them to make a purchase.

[DanieIMonteiro]

What I've learned from programming and heard from many senior level programmer is to never document WHAT your code does - rather document the WHY. Like, WHY did you solve it like this? Is there a reason WHY you store the data in this form? WHY do we even need this?

This in combination with good method names really helps a lot

[shieldgenerator]

this was both informative AND entertaining, a very rare combo in code tutorials

[Patrickblox]

One of the only channels whose videos I always watch because I always learn something new. Thank you, Charles, your videos are extremely valuable.

[tafellappen]

imho whats worth mentioning here is when you refactor like this dont just assume it works like it did before, especially if youre not the only one working on the code. As a developer my dad has many a horror story about how an overconfident dev was like "wow this code bad right here i can write better code" without checking with anyone or making it clear enough that they changed anything, and suddenly everything is broken and nobody knows why.
even for code that is 100% me, maybe im just dumb but theres countless times where i go to refactor even the simplest thing in my own code and it just stops working because i forgot something little or messed up my syntax

and honestly, im not sure how i feel about just automatically deleting "zombie code" or "redundant" comments. as with most things in code it depends - the example youve given definitely seems to warrant the cleanup. I think that every time you see something like this its worth considering whether its still serving any purpose. Maybe as i gain confidence and skill as a developer I'll become more comfortable with the idea of comments like these having to go, but right now it makes me uncomfortable.
I've found that I always need to comment my code like I take notes for a math class - which means i need act like im talking to a literal brick. It not only helps me think about the code as I write it, but also greatly helps me rebuild my working mental model of, basically, how i think about my code, whenever I pick up where i left off. Sometimes my comments probably look redundant to others, but my brain just needs to see something written in a color that isnt the color of the code. Much like I wouldnt want someone to just say "you dont need this" and throw away half my math notes, I wouldnt want someone to do that to my probably seemingly redundant comments. If i dont need them anymore, I will know and remove them.
I've worked with uncommented code in an sdk that was very descriptive of the intent but it didnt fully work. we tried fixing it but the code structure leaned so heavily into "describing intent" that the actual logic was so abstracted that it was nearly impossible to follow. the method calls were seemingly *endlessly* nested and when you finally reached the last one you still had no idea how the code actually functioned. after days of this and zero progress we decided that we would be better off foregoing the sdk entirely, immediately everything got much smoother.
in a similar manner, the zombie logic i leave also usually serves a purpose to me. if its not gone i probably am still using it, if for no reason other than to use as a checklist as i write the new logic. and while it is in source control, by deleting you could be forcing someone to have to spend time hunting around source control in the future.

tl;dr; a badly worded way of saying i really cant see myself irl being as carefree with deleting comments as you were in this video, im too afraid of throwing away someone's notes.

[cesargamedev]

I really like the idea and in fact I was already doing similar things in my code, but I don't think this is enough to avoid using comments as a whole. Also, comments have been very useful for me, as thanks to them I've been able to create documentation websites using only doxygen and no aditional work, as it reads the comments and converts them to clear documentation.That said, encapsulating conditions and other similar functions is really nice, more if they're something you'll need to use more than once, but using them to substitute all of the code willl generate a lot of code just for properties, which I think could be a problem if you need to change those properties at some moment. So my position is, use this to reduce the complexity of code and the reliance of comments but find a balance so that you can keep at least comments for the methods and such.

And yeah, keep your code clean and write selfexplaining names for variables, methods and all of that.

[BabakSalimi]

I want someone like Charles to review my code!
The problem with not working in a company is you don't have a senior checking your code, then you end up with a mess in your code and you have to learn it the hard way!

[jeniferirwin]

Up until now I wondered why I've seen so much code that appeared to be wasting time declaring variables that didn't seem to need to be declared. You explained this so well that now I FINALLY understand it, and I thank you! Also... oh noes! Poor Charles! I hope Barles doesn't have to 'delete' him!

[RictorScale]

This is extremely helpful. I always knew that we should use variables instead of hardcode value for maintainability if we need to change something but I never thought of using varibles purely for readability. That makes SO MUCH SENSE

[tommallama]

Only you could write a code talk with a Halloween theme and still make perfect sense xD

[nikolaynakorkeshko]

After reading comments for this video:
Some tips for people who really wants extract all code parts to different methods for better understanding:


Extract all code that you dont cleary understand in very big project, also do it with every frequently called code => slow down your program.

Check this out: simple inline calculation vs method call(with same calculation inside) results for 1 million calls:
Inline: 10, 6802 mills
MethodCall: 29, 5754 mills
Results are same but execution time(perforamance) different. Inline 3 times faster. You can do same test.
If you really want to understand some code parts when you back to it, just use #region instead of move all code to whole method and consume you cpu time(imagine it runs on slow mobile cpu, not on pc)

Next tip. If you are team lead or just you development team consists of 3+ programmers and some of them can be changed over time, then you obviously need ready to use documentation(website, generated from xml comments in code) for your team. That will makes some processes run faster.

Next tip. If you don't want see a lot of comments in your code, you can move docs in different files and link it via xml special tag using just one comment line

Last tip. Computer dont do the magic, everything has a price. Remember that

[papermartin]

infallible code socially distances from himself somehow

[mrp]

Awesome video! Great production quality as always, that Halloween part was great.

[Bisirsky]

Wow, I'm a linguist and it's the best explanation why I was so irritated by someone's else code.

[bogdanzarzycki]

It's a great eye opener. I was aware of the problem, but not really knew exactly how to solve it nicely. Just extract everything you can into lambda type properties, that i love so much.

[HoboKnight]

I've been pushing for this sort of change at my work place. Currently we have strict rules about commenting everything that results in comments on getter methods like:
/*
* gets X
*/
public int getX(){}

etc

Meanwhile X might be an actual variable name that does not correspond to an x co-ordinate and takes 10 minutes of reading through the code to figure out.

One counter point to the sort of self-documenting code you suggest though, performance. I know that 99% of the time there is no real performance hit for all these method calls, but I have talked to people working in AAA games that have told me they have tons or duplicated, inline code in their engine because the overhead of function calls is too much to maintain 60fps when added up over the whole project. So these people rely heavily on comments to explain algorithms etc that would be better encapsulated in a method call. When working on less demanding games, or on enterprise software though, I definitely prefer to have clearer code and remove the comments.

[davidrogers]

I do recommend proper naming conventions for methods, steer away from the "for each" traps. Strong commented code creates ease for people from different disciplines especially at times when refactoring is a thing. Additionally, creating accessible information that doesn't require you to go into the code is A+.

[fmproductions]

Interesting topic and good video! Reminds me of some parts in the book "Clean Code" by Robert C Martin. There is also the notion that other team members often won't update comments when a method is changed and that methods and variable names should be self explanatory in an effort to reduce the need for comments as much as possible. I think I should revisit the book someday since my memories of the concepts are already a bit fuzzy, but it is a good read. Having methods for small checks that have a verbose name is also mentioned to be a good idea.

[RishabKapadia]

i was just about to comment my entire code base (small). thanks. love the content style and your speach. subscribed.💙

[kylebarvel]

If you need help remembering what zombie code is, just remember 1- they are the undead and 2- they look green (well in most cases)

[simonhagfalk]

Great examples of how to document code easily. Also big + for the comedy in this one.

I like to write function names that are descriptive and reduces the need for comments aswell. Sometimes the method names get a bit long though.