Would-be developer in need of orientation

[hervebronnimann]

My background: I've taught computer science in college (visiting prof at Princeton, tenured at NYU Poly), left academia to pursue software at Bloomberg for a few years (maintained their version of the C++ Standard Library there), participated in some C++Boost and C++14 standardization committees, and for the past five years been working in Java for the financial industry. I'm new with Magic (started playing back in September because of my son), but I've fell in love with the game... I've benefited immensely in my game by playing against the forge AI in booster draft and sealed deck.

This is a great project and I'd love to contribute. One problem is that the code base is a bit too large to grasp all at once, and as a new player I don't know much about various formats like EDH, or cube, or quest mode, or gauntlet, etc. Nevertheless, I feel I could and would love to contribute.

What I feel I could easily contribute that would help the most players get started is to document the code. I'm not speaking about the method documentation (many times, there's no need for it except to document a contract's boundary cases). I'm speaking about module/package documentation of the style: "This section of the code does this. It interacts with that other package via these classes. If you're looking for this, you'll find it here (or there...)" For instance, it took me a while to find the .txt file that documents cards, and who reads it, and how they parse that info. Finding the class that loads the HQ and LQ pictures and patching it to only load, say, M15 and KTK because I don't play the other formats. A lot of the .txt files I've read are not self-describing - when it would be so easy to make it so. Etc. That kind of high-level information seems to be missing in the Forge SVN repo. When confronted with a new project, that's what most developers look for.

I haven't found (yet, and I've not read most of the code by far) anything resembling this. There's also no unit test. I'm really good at both those things and would love to start beefing up the code and helping out. I find it a great way to learn code for myself too, which is ultimately my objective.

So is anybody willing to share a bit of that knowledge with me and give me a boost on the path of Forge enlightenment? Of course, as any dev worth his or her salt, I can probably do that by myself by simply reading the code (it's a medium-size project). But it takes time and I don't have that much, so it would speed me up, and would also help write down info that's not readily knowable from the code (for instance, how the code evolved, or why some class is written in a certain way, or why functionality is split in classes/packages the way it is - usually for reusability with some part that I may not be aware of).

I'm turning on notifications for replies to this post, so just reply here or message me privately. Thanks.

[friarsol]

Hey Herve,

I'll try to give a little bit of rundown as best I can, but unfortunately I won't have the time to do so today. Have you already checked out the Wiki? I believe at least some of your basic questions we may have answers for on there, although I'm not really sure any one person can give a suitable answer to how the code evolved as there have been plenty of different people coming in and out of the dev team in the last few years.

Which text files are you specifically talking about not being self describing? Can you give an example of what you mean?

[oskarolw]

I think what you describe would be very useful. I have tried to get into the code a bit myself but I feel like I can't really wrap my head around all of it.

[hervebronnimann]

Sol: thanks for your reply. You can message me privately at your convenience (my email is my username followed by @me.com) I appreciate your suggestion (elsewhere) to start learning the code by fixing a small problem or making small improvements. I plan to do just that. Still, it'd be great to have a roadmap. Let me just illustrate what I mean.

Re: text files: take for example anything in forge-gui/res. Say forge-gui/res/ai/Reckless.ai; I can see it turns a bunch of options. I can do a search for the options, and see they do not occur i String literals, but as enums AiProps translated toString(). I can then figure out how they're used with FindUsages in IntelliJ (e.g. MULLIGAN_THRESHOLD in forge.ai.ComputerUtil.wantMulligan()). The AIProps is actually nicely documented. What's not documented is the link to the class AIProps in forge-gui/res/ai. I could find it relatively easily but someone with less experience may look only for them as Strings and may be baffled not to find them referenced anywhere in the project. A package-doc.java inside that directory would've made everything crystal clear.

Taking another example: forge-gui/res/cardsfolder. It has a lot of cards, organized alphabetically, but what is the syntax of each card (necessary to check if there's a bug in the card description when some unexpected behavior occurs during gameplay or testing). Of course, one can say the code that reads it documents the syntax - but good luck finding that. It took me a while to find forge-core/src/main/java/forge/CardStorageReader.java, but that's only the beginning. All the parsing seems to lie in loadCard(), returning CardRules, so now we must understand all the classes collaborating into CardRules, which is basically all of forge.card package in forge-core. I can figure it out by unraveling the code, but documentation would just make this so much easier. And in case one wonders what the difference between forge.card and forge.game.card is, a documentation would convey that very nicely.

Another example: I don't know the syntax of forge-gui/res/blockdata/*, it seems each file has its own syntax and I don't know where they are read from. Not that it matters too much for my primitive usage of Forge (I'm a novice, only playing booster and sealed drafts).

Btw, I can't really understand why all that's in forge-gui/ as for me ai profiles would better belong to forge-ai/ and cards descriptions would more naturally belong to forge-game/ or forge-core/. I always struggle to remember the location of those cards description (tip: I just look for Ctrl-Shift-N and type e.g. gobin_rabblemaster.txt, that brings up the location immediately). Again, a top-level doc giving some pointers as to the reasoning behind the organization would make things easier to find.

Finally, I should say that I'm very much in awe of the source code. It's only my desire to make more accessible. All of the above shouldn't be read as a put-down, on the contrary it's very nice that I can describe the classes that collaborate into making the card rules as a single java package. That reflects the sound organization of the code. But figuring it out should not require extensive delve into the code, unraveling FindUsage recursively; it ought to be documented explicitly and from the top-down, for the reader. When the reader wants to become a developer, then it's understood they need to start reading the code minutiae. Till then, I just want to make

[friarsol]

If you don't mind I'll keep the conversations on the forums, just so other people that were more familiar with certain parts can chime in if my memory of events are incorrect, or I misrepresent some structure while trying to give an overview.

Btw, I can't really understand why all that's in forge-gui/ as for me ai profiles would better belong to forge-ai/ and cards descriptions would more naturally belong to forge-game/ or forge-core/. I always struggle to remember the location of those cards description (tip: I just look for Ctrl-Shift-N and type e.g. gobin_rabblemaster.txt, that brings up the location immediately). Again, a top-level doc giving some pointers as to the reasoning behind the organization would make things easier to find.

I know this off the top of my head, and doesn't require having my codebase to point out the general structure of things. The forge-gui/ folder structure is a remnant of Forge's history. For a while, the original developer (mtgrares, no longer active on the project) wrote Forge mostly so he'd have something to play with since he didn't have access to a FLGS. Being a fledgeling developer he packed Forge into a single project, everything lived in the equivilant of today's forge-gui/ folder (IIRC just called "forge"). Over time a few different developers, many of which are no longer actively developing, have made sweeping changes to both the structure of the project, as well as the architecture. (For those curious, this is our project from 3.5 years ago when we were still using the old structure)

At the time the latest structural split happened (ai, core, game, gui, net), forge-gui/res/ was referenced everywhere and this was before we had standalone Profiles. I believe the decision was made to leave forge-gui/res/ alone, to minimize conflicts for both the development team, and users who had customized their resources. If we started fresh, it'd make sense to have each project folder have their own specific resources directory, Core inheriting a majority of those we have now. I think it mostly became a defacto location where all active developers knew where resources lived. Yes, that may not help new developers all that much when looking from a top down level, so I'm sure it'd be helpful for the next guy if there were at least some sign markers.

I wouldn't be surprised if sometime in the future, someone is motivated enough to migrate some of these resources over. Until then people interested in creating new features will just follow the structure that already exists, where forge-gui is the catchall location for all resources.

I'll try to squeeze an hour in later this week to actually follow up, but my evenings are looking pretty packed in already. If someone else with a bit of free time that's familiar with at least part of the larger architectural pieces, feel free to speak up.

[hervebronnimann]

If you don't mind I'll keep the conversations on the forums, just so other people that were more familiar with certain parts can chime in if my memory of events are incorrect, or I misrepresent some structure while trying to give an overview.
.......
I wouldn't be surprised if sometime in the future, someone is motivated enough to migrate some of these resources over. Until then people interested in creating new features will just follow the structure that already exists, where forge-gui is the catchall location for all resources.

Thanks Sol. That's very helpful and informative. I wouldn't mind doing the refactoring in the future, but I'll wait until I've contributed a number of low-level patches and am much more familiar with the code. Till then, it's probably much more effective to document the current structure anyway.