Job Queue for Strategy Game

I've posted a revised version of this here.

I posted about this basic problem a while ago, and I got the recommendation to move the code for managing the Jobs of my game to another class. I have been working on it for a little while now, and I have code that I believe is ready for review. The result is three classes, one for the Queue itself, one for the Job objects that count themselves down, and one for the Units which the Job class creates in order to count itself down. These Units are exposed to Workers when they are in the appropriate state in order to limit the number of workers at one time. The workers do not actually enter the queue, but only enter the Floor that contains the Queue. I'm hoping to hear about any major pitfalls or problems I may be falling into, and also whether or not the design makes sense to other programmers looking at the code.

DTJobQueueStates.h

typedef NS_ENUM(NSInteger, JobQueueStates){
    JobQueueIdle = 0,
    JobQueueWorking,
    JobQueuePaused
};

DTJobQueue.h

#import 
#import "DTJob.h"
#import "DTJobQueueStates.h"

@interface DTJobQueue : NSObject 

-(void) updateJobQueue;

@property JobQueueStates jobQueueState;
@property NSMutableArray *completedJobsForPickup;

-(void) addJob: (DTJob *)job;
-(JobType) activeJobType;
-(void) cancelAllJobs;
-(void) abandonCurrentJob; //used when dwarves die

-(BOOL) areJobSlotsAvailable;
-(int) remainingJobSlots;
-(void) reduceRemainingJobSlots;
-(void) increaseRemainingJobSlots;
-(NSMutableArray *)availableJobSlotsForWork;

-(void) finishOneJobUnit;

-(int) numberOfJobsInArray;

@property NSMutableArray *blocksOnFloor;
@property NSMutableArray *itemsOnFloor;
@property NSMutableArray *enemiesOnFloor;

@end

DTJobQueue.m

```
#import "DTJobQueue.h"
#import "DTGroundBlock.h"
#import "DTItem.h"
#import "DTEnemy.h"

@implementation DTJobQueue {
DTJob *_activeJob;
NSMutableArray *_jobArray;
}

-(id) init {
self = [super init];
if (self) {
_jobArray = [[NS

This all seem pretty complicated, but is it too complicated? Or rather, is it too complicated to understand, or more complicated than it needs to be?

My answer? I don't know. Maybe. I mean, you're trying to do complicated stuff, so of course the code is going to be complicated. There might be a more simplistic approach, and perhaps someone will come in with a super-answer and give you that more simplistic approach. But here's the problem I have.

This code is complicated. Let's presume that to the best of your knowledge, it's working perfectly as intended right now.

Let's say you spend 6 months doing other things. Maybe you're working on other parts of the game. Or maybe you've released the game and you've started on another project. But 6 months down, a pile of user complaints/comments about the job queue system start to pile up. You want to go straight back to this code base and try and sort it out.

How many hours/days are you going to spend just re-orienting yourself with this code and try to understand it yourself after having not looked at it for 6 months before you understand it to the point that you feel like you can start attempting to make fixes/improvements?

The problem is, you're asking us whether or not it's too complicated, which means you think it's pretty complicated code, but... you've left your future self almost no comments!

There are two "omitted for brevity" comments.

There are three comments left as markers for something that will be changed in the future when more features are added.

None of these five comments are particularly helpful to any future programming trying to fix/improve this code. And outside of these five comments, you've left just 7 comments by my count.

Now, sometimes in Objective-C, it's okay to leave very few comments. We have a tendency to like very long, very verbose method and variable names--we love self-documenting code! But self-documenting code only goes so far. When it comes to trying to understand the bigger picture of what's going on, sometimes we do need some comments.

When I start to write a class that I know will be doing complicated things, the first thing I do at the top of the .h file is a big block quote with a summary of what the class does. A big picture overview in plain English of the class. Additionally, numerous method declarations will have their own block quote with a plain English description of what the intended use of the method is.

Consider if you've hired a programmer to help you. You want him to figure out a bug that has something to do with the job's system. With none of these plain English comments, it can be a bit of a guessing game and he's spending quite a lot of time tracking down where he might need to make some changes.

StackExchange Code Review Q#55735, answer score: 3