Welcome Guest! To enable all features please Login or Register.

Notification

Icon
Error

Options
Go to last post Go to first unread
Offline DeadRabit  
#1 Posted : Friday, December 27, 2013 6:18:47 PM(UTC)
DeadRabit

Joined: 12/27/2013(UTC)
Posts: 1
Location: UK

Hi, Just downloaded Delta Engine for the first time :) looking forward to picking everyone's brains.
Surprised to find that none of the samples have a single comment between them (defeating the point somewhat Glare), even more surprised that I seem to be the first to bring this up on the forums. Are there any samples available on the web with comments?
I can read code faster then books so I'd rather find a different engine then sift through pages of documentation.
Cheers,
D.R


(apologies, just noticed the Samples forum >.<, mods feel free to move this)

Edited by user Friday, December 27, 2013 6:22:08 PM(UTC)  | Reason: Not specified

Wanna join the discussion?! Login to your forum accountregister a new account. Or Connect via Facebook Twitter Google

Offline elasto  
#2 Posted : Friday, December 27, 2013 7:32:17 PM(UTC)
elasto

Joined: 8/23/2011(UTC)
Posts: 245

Thanks: 6 times
Was thanked: 12 time(s) in 11 post(s)
Hi DR!

The first thing to say is that there is an intermediate between the code and the documentation - the Tutorials. They are surely the best place to dive into if you want to get a feel for what the engine can do and how to do it. Each mini-topic is half a dozen lines of code or so and a great deal of explanation.

---

On the topic of comments, we are strong believers in Clean Coding. A strong principle therein is that if you have to put a comment in a piece of code you've failed to write it clearly enough - and rather than adding that comment you should be, say, splitting up that class or method into smaller, more self-explanatory chunks, and put effort into how you name your classes, methods and variables.

Comments take a lot of time and effort to ensure they haven't diverged from the code they are explaining. Would you ever really trust a comment therefore? Especially since you say you can 'read code faster than books' - wouldn't you always prefer to read the code to find out what it really does?

So we rarely comment - instead we have many strict rules all with the goal of making the code as self-explanatory as possible.

For example, we have a soft limit of 3-5 lines of code in a method - and a hard limit of 10 lines. Once a method gets beyond that it starts to become harder to follow and ought to be split up. A class needs a very good reason to go beyond 200 lines. Probably most of our classes are under 100 lines long.

We also have a general rule to avoid code within braces; It taxes your train of thought unnecessarily. Instead that subsection of code will typically be be moved to its own self-contained, self-explanatory method.

You'll see that the entire engine has been written with these and other principles in mind.

Yes, an engine as deep and wide-ranging as Delta Engine is innately a complex thing, there's no avoiding that - but the goal is that you should be able to dive into any class and read the code from top to bottom almost like a novel. Obviously the degree to which we have succeeded is for everyone else to judge, but that is what we are going for :)

---

Feel free to dive in and ask as many questions and make as many suggestions as you wish, we're here to help!


- Phil
Offline Benjamin  
#3 Posted : Saturday, December 28, 2013 12:55:58 AM(UTC)
Benjamin

Medals: Admin

Joined: 8/20/2011(UTC)
Posts: 1,421
Location: Hannover

Thanks: 18 times
Was thanked: 97 time(s) in 92 post(s)
As PG said the amount of comments in any code (engine, tutorials, sample games) is on purpose down to a bare minimum. You will usually only find some comments in public class summaries. This is in contrast to many comments from 2 years ago (v0.9.5 and earlier) and anything else you might pick up from me on the web from the past like:
http://xbox.create.msdn....talog/sample/racing_game
http://www.codeproject.c...n-which-Helps-you-to-Com
http://www.codeproject.c...-to-automatically-compre
etc.

I agree it takes a bit of time to get used to it, the easiest way to adjust is to think of the actual source code as comments. More importantly all methods are short in a few lines and the name of the method is describing what it is doing. There is also a lot of things, which are obvious to any C# programmer, which do not need to be repeated over and over in source code (like this is a try/catch block, this is checking this, etc.)

Maybe we can talk about an introductory tutorial/sample game CodeProject article, describing how to create a 3D game or demo with the DeltaEngine and then converting it to different platforms. Would this be useful to you?
Rss Feed  Atom Feed
Users browsing this topic
OceanSpiders 2.0
Forum Jump  
You cannot post new topics in this forum.
You cannot reply to topics in this forum.
You cannot delete your posts in this forum.
You cannot edit your posts in this forum.
You cannot create polls in this forum.
You cannot vote in polls in this forum.

Powered by YAF.NET | YAF.NET © 2003-2018, Yet Another Forum.NET
This page was generated in 0.123 seconds.