Documentation?

[ReleeSquirrel]

Is there any documentation outside of the comments in the code?

I'm going through the code in my spare time, trying to work out the logic and flow of the program. As I do so I write what the program is doing at each stage in plain english.

Is there anything like that already made, to simplify understanding the system? It could save me the trouble of making my own.

Also, what is the Logger class? I'm guessing it's for logging...

 

[Skaldarnar]

Hey, there is this thread about logging. So, basically its for logging, but you can specifiy the level easily for debugging, non critical errors, ...
I don't think there is great (plaintext) documentation, its quite scattered over the forums (forum overview thread) and the wiki.
If you are collecting the information it would be quite useful to share with others... maybe we should make a new repo (what do you think, Cervator ?) for some LaTeX-documention that can easily be exported to pdf and stuff.... Some nice diagramms, work flows, code examples in one place - sounds nice

 

[Immortius]

On the world/block end of things I'm not aware of much documentation, although I describe some of the block settings in the Mod Incubator thread. On the entity system (the system behind all non voxel game logic) this document describes the high level concepts: Entity System Concepts. Entity System Architecture goes into some detail, but it is quite dense.

I am hesitant to go much further with documentation until after multiplayer is added, because that will likely cause all sorts of changes.

 

[Cervator]

We have a few scattered wiki pages, the incubator threads, and some misc. Yeah, classic open source style it isn't very well put together or comprehensive ...

I'd like to focus on very light higher-level write-ups on wiki pages (with some nice diagrams and such) like the ES stuff, block shapes, and similar, matched with more detailed feature info (for devs) in Incubator threads but most of all in-game created documentation (Javadoc, feature-specific JSON, etc) that at build-time is scraped and auto-published to the wiki as a guide.

Skaldarnar - you think we need something new and separate? I fear that the more sources/places we have for docs the less up to date they'll tend to be. Thus my focus on grabbing stuff from within the code itself. Of course, that relies on us actually documenting well at the code level - maybe we should enable Javadoc in Checkstyle

ReleeSquirrel - please feel free to share anything you come up with and help tie together what we have - definitely an area that'll need work over time

 

[Skaldarnar]

[...] Of course, that relies on us actually documenting well at the code level - maybe we should enable Javadoc in Checkstyle

Ok, that would be a good idea, forcing us lazy developers to document everything

 

[Wernesgruner]

Honestly I think a proper javadoc would be a great start and it really isn't hard at all to just write a few line right after you worked on a method. And once one of those crazy archivist type guy joins the project he won't give up after just a few classes because he needs to look at every single line of code to understand what a method does.

 

[ReleeSquirrel]

So hey, I'm still going through the code bit by bit, following the logic. I've just passed the part where the Main Menu begins and I'm looking through some of the essential code. My personal write-up isn't ready to be shown yet, but in the mean time after looking through the code for a while I've gotta say something.

Immortius, dude, you are an epic coder, full of wizard tricks and clever ways and means, but for the love of everything please please PLEASE comment your code! I don't know where you learn all this stuff but if you expect people to be able to just understand it, you're putting way too much faith in programming schools!

I mean, let's be serious, the other code isn't much better. But the parts you've done don't even say what they are, apart from their name.

I go to StateMainMenu.java and I get

/**
* The class implements the main game menu.
* <p/>
* TODO: Add screen "Multiplayer"
* TODO: Add animated background
*
* @author Benjamin Glatzel <benjamin.glatzel@me.com>
* @author Anton Kireev <adeon.k87@gmail.com>
* @author Marcel Lehwald <marcel.lehwald@googlemail.com>
* @version 0.3
*/

I go into EntitySystemBuilder.java and I get

/**
* @author Immortius
*/

I mean, throw me a bone here, guys! XD

Especially when you call functions outside of the current class, it would be really nice if you made a short comment saying what you were actually doing. I'm going up and down all sorts of chains of classes to figure out what this and that call are for.

I'm in the EntitySystemBuilder class right now 'cause it's the first thing called in the init function of the StateMainMenu class, and EntitySystemBuilder is all about making a PersistantEntityManager, so that's two right there. Then right in the EntitySystemBuilder you're using ComponentLibraryImpl and PojoPrefabManager, which implement some interfaces, and what does Pojo even mean?

I'm pretty sure I understand what you're doing in this code, and it's impressive, but it's also really hard to read without a lot of running around.

 

[Immortius]

I guess that is partially because I don't really expect people to read through the code like that. Programs are generally modular and non-linear, a linear reading through them is always going to be a bit convoluted.

I could do a better job with comments, yes. Admittedly I am a little too eager to get the current feature done/next feature started, due to limited available time to work on things in the first place. I also feel a little pressured to have things working for upcoming needs. And half the time I'm refactoring and expanding on existing code which lacks comments anyway.

On the other hand, I have been trying to write self-documenting code (I am working to improve on this too) - making the names of variables, methods and classes describe their purpose, and splitting up methods into a number of sub-methods with similarly descriptive names. The EntitySystemBuilder builds the EntitySystem. Unless I have something to say beyond that I don't think a comment is necessary (there should be a comment describing how it builds it though).

The comment for StateMainMenu tells you nothing the class name doesn't - in fact it is misleading because the main menu is actually in a different class, and StateMainMenu just loads it up. Until there is more to write about a something than just a reiteration of its name, I don't see any value in doing so - it adds clutter and something extra to worry about updating as the code changes.

And where I have been documenting it has been more intended for users of code - ComponentLibraryImpl doesn't have much (and still needs refactoring) but the interface it implements is much better documented. Everything that is true for the interface is necessarily true for the implementors. Most users only work through the interface and don't need to know the gory implementation details - that would only come up if it needs maintenance.

And finally multiplayer is coming and that will cause all sorts of changes. Once that is done I will be much happier to spend time doing cleanup, documentation and tutorials.

On POJO - it is a Java acronym meaning Plain Old Java Object. There is a little history there - I was originally intending to replace the POJO implementation of the entity system with one running on OrientDB, but the prototype proved too slow. I guess I overestimate how well known the acronym is, it could be renamed to InMemory or similar instead.

 

[ReleeSquirrel]

Part of the reason I'm going through the code like this is because I had a hard time understanding the modular structure you used. Part of the reason for that is the lack of comments, and documentation outside of the code.

If you can't comment every little thing, even a short paragraph at the start of every object explaining its purpose and its position in the system would be awesome. It'll tie right into the JavaDoc too. Even if you have to change it later, a few english sentences shouldn't take very long, should it?

For now while I work on figuring out the system, I'm thinking of making another document, maybe a diagram, that shows the parts of the system and the classes within it. Right now I'm working through the Entity Manager, for example. There's a couple documents you linked me to earlier in the thread that have been helpful understanding it, but it's difficult to recognize the implementation against the theory. A nice diagram or list saying what classes belong to what system and what they do would be really handy. That said, I'm not a documentation wizard. Documentation strategies and traditions, and technologies aren't really explored as part of a college education.

I'll definately have to take a closer look at the interfaces, if they're where the structure and comments are. Thanks for pointing that out.

Also thanks for the Pojo explanation. I haven't been using Java that long, and mostly just standard Java, so the idea of using objects based on non-plain java objects is interesting.

 

[Cervator]

I think this itself is sort of a useful documentation exercise, I've taken to add documentation when I tinker with a few classes and hope others would be able to do that too, then maybe poke for review in here somewhere to make sure said documentation is about right.

For interface / implementation I've dug up the inheritdoc tag for implementers - which technically is excessive as Javadoc will pick up parent classes/interfaces to grab doc from, but it helps point out when you're looking at an implementation that oh yeah, there's documentation in the interface.

The view javadoc shortcut in IntelliJ has also proven useful, even with just a few words beyond method names and such

Diagrams are good if they're high level enough to not go obsolete too fast. A picture is worth a thousand words and all that.

 

[ReleeSquirrel]

Actually I was planning on making it a very low level diagram, with references to specific classes. But you make a good point.

Maybe I should make something easy to update and change. A simple web page perhaps? I could do it with some HTML and CSS, and then I could just add and remove classes as they come and go from the system.

 

[Cervator]

Ideally we'd just use something existing, like our GitHib Wiki (which can itself be edited from an IDE and submitted via Git)

I don't think it has any sort of "draw" plugin, though, so we'd probably be limited to plain ole images. There are some fancier features I've briefly looked at we can enable.

May have to submit images to TeraMisc, unless those can be submitted to the wiki repo via Git and referenced that way

 

[ReleeSquirrel]

I can screenshot an HTML based diagram, and it wouldn't be much more difficult to update that way.

I'm not terribly familiar with how the GitHub Wiki works, though.

 

[Cervator]

GH wikis are pretty straight forward, you can enable one on the Admin panel of your fork on GitHub then play around in it. Uses MarkDown, which is easy (see a couple of the links in my previous post). You can push entire wikis around with Git, like pulling the main Terasology one to your own fork or the other way around. Or I can just give you edit rights to the main one