How to warn other programmers of class implementation

In such cases, it is best to use the type system of your language to help you with proper initialization. How can we prevent a FooManager from being used without being initialized? By preventing a FooManager from being created without the necessary information to properly initialize it. In particular, all initialization is the responsibility of the constructor. You should never let your constructor create an object in an illegal state.

But callers need to construct a FooManager before they can initialize it, e.g. because the FooManager is passed around as a dependency.

Don't create a FooManager if you don't have one. What you can do instead is pass an object around that lets you retrieve a fully constructed FooManager, but only with the initialization information. (In functional-programming speak, I'm suggesting you use partial application for the constructor.) E.g.:

ctorArgs = ...;
getFooManager = (initInfo) -> new FooManager(ctorArgs, initInfo);
...
getFooManager(myInitInfo).fooMethod();

The problem with this is that you have to supply the init info every time you access the FooManager.

If it's necessary in your language, you can wrap the getFooManager() operation in a factory-like or builder-like class.

I really want to do runtime checks that the initialize() method was called, rather than using a type-system-level solution.

It is possible to find a compromise. We create a wrapper class MaybeInitializedFooManager that has a get() method that returns the FooManager, but throws if the FooManager wasn't fully initialized. This only works if the initialization is done through the wrapper, or if there is a FooManager#isInitialized() method.

class MaybeInitializedFooManager {
  private final FooManager fooManager;

  public MaybeInitializedFooManager(CtorArgs ctorArgs) {
    fooManager = new FooManager(ctorArgs);
  }

  public FooManager initialize(InitArgs initArgs) {
    fooManager.initialize(initArgs);
    return fooManager;
  }

  public FooManager get() {
    if (fooManager.isInitialized()) return fooManager;
    throw ...;
  }
}

I don't want to change the API of my class.

In that case, you'll want to avoid the if (!initialized) throw; conditionals in each and every method. Fortunately, there is a simple pattern to solve this.

The object you provide to users is just an empty shell that delegates all calls to an implementation object. By default, the implementation object throws an error for each method that it wasn't initialized. However, the initialize() method replaces the implementation object with a fully-constructed object.

class FooManager {
  private CtorArgs ctorArgs;
  private Impl impl;

  public FooManager(CtorArgs ctorArgs) {
    this.ctorArgs = ctorArgs;
    this.impl = new UninitializedImpl();
  }

  public void initialize(InitArgs initArgs) {
    impl = new MainImpl(ctorArgs, initArgs);
  }

  public X foo() { return impl.foo(); }
  public Y bar() { return impl.bar(); }
}

interface Impl {
  X foo();
  Y bar();
}

class UninitializedImpl implements Impl {
  public X foo() { throw ...; }
  public Y bar() { throw ...; }
}

class MainImpl implements Impl {
  public MainImpl(CtorArgs c, InitArgs i);
  public X foo() { ... }
  public Y bar() { ... }
}

This extracts the main behaviour of the class into the MainImpl.

The most effective and helpful way to prevent clients from "misusing" an object is by making it impossible.

The simplest solution is to merge Initialize with the constructor. That way the object will never be available for the client in the the uninitialized object so the error is not possible.

If you for some reason need to be able to access the uninitialized object before initialization, then you could have the two states implemented as separate classes, so you start out with an UnitializedFooManager instance, which have an Initialize(...) method which returns InitializedFooManager. The methods which can only be called in the initialized state only exist on InitializedFooManager. This approach can be extended to multiple states if you need to.

Compared to runtime exceptions, it is more work to represent states as distinct classes, but it also give you compile-time guarantees that you are not calling methods which are invalid for the object state, and it documents the state transitions more clearly in code.

I would normally just check for intiialisation and throw (say) an IllegalStateException if you try and use it whilst not initialised.

However, if you want to be compile-time safe (and that seems laudable), why not treat the initialisation as a factory method returning a constructed and initialised object e.g.

ComponentBuilder builder = new ComponentBuilder();
Component forClients = builder.initialise(); // the 'Component' is what you give your clients

and so you control the objects creation and lifecycle, and your clients get the Component as a result of your initialisation. It's effectively a lazy instantiation.

I'm going to break a little bit from the other answers and disagree: it's impossible to answer this without knowing what language you're working in. Whether or not this is a worthwhile plan, and the right sort of "warning" to give your users depends entirely on the mechanisms that your language provides and the conventions other developers of that language tend to follow.

If you have a FooManager in Haskell, it would be criminal to allow your users to build one that isn't capable of managing Foos, because the type system makes it so easy and those are the conventions that Haskell developers expect.

On the other hand, if you're writing C, your coworkers would be entirely within their rights to take you out back and shoot you for defining separate struct FooManager and struct UninitializedFooManager types that support different operations, because it would lead to unnecessarily complex code for very little benefit.

If you're writing Python, there's no mechanism in the language to let you do this.

You are probably not writing Haskell, Python, or C, but they're illustrative examples in terms of how much/how little work the type system is expected and able to do to do.

Follow the reasonable expectations of a developer in your language, and resist the urge to over-engineer a solution that does not have a natural, idiomatic implementation (unless the mistake is so easy to make and so hard to catch that it's worth going to extreme lengths to make it impossible). If you don't have enough experience in your language to judge what's reasonable, follow the advice of someone who knows it better than you.

When I implement a base class that requires extra initialisation information or links to other objects before it becomes useful, I tend to make that base class abstract, then define several abstract methods in that class that are used in the flow of the base class (like abstract Collection<Information> get_extra_information(args); and abstract Collection<OtherObjects> get_other_objects(args); which by contract of inheritance must be implemented by the concrete class, forcing the user of that base class to supply all the things required by the base class.

Thus when I implement the base class, I immediately and explicitly know what I have to write to make the base class behave correctly, since I just need to implement the abstract methods and that's it.

EDIT: to clarify, this is almost the same as providing arguments to the constructor of the base class, but the abstract method implementations allow the implementation to process the arguments passed to the abstract method calls. Or even in the case of no arguments being used, it can still be useful if the return value of the abstract method depended on a state that you can define in the method body, which isn't possible when passing the variable as an argument to the constructor. Granted you can still pass an argument that will have dynamic behaviour based on the same principle if you'd rather use composition over inheritance.

As you seem to not want to ship the code check to the customer (but seem fine to do it for the programmer) you could use assert functions, if they are available in your programming language.

That way you have the checks in the development environment (and any tests a fellow dev would call WILL fail predictably), but you will not ship the code to the customer as asserts (at least in Java) are only selectively compiled.

So, a Java class using this would look like this:

/** For some reason, you have to call init and connect before the manager works. */
public class FooManager {
   private int state = 0;

   public FooManager () {
   }

   public synchronized void init() {
      assert state==0 : "you called init twice.";
      // do something
      state = 1;
   }

   public synchronized void connect() {
      assert state==1 : "you called connect before init, or connect twice.";
      // do something
      state = 2;
   }

   public void someWork() {
      assert state==2 : "You did not properly init FooManager. You need to call init and connect first.";
      // do the actual work.
   }
}

Assertions are a great tool to check for runtime state of your program that you require, but don't actually expect to anyone ever doing wrong in a real environment.

Also they are quite slim and don't take up huge portions of if() throw... syntax, they don't need to be caught, etc.

The way I've solved this problem before was with a private constructor and a static MakeFooManager() method within the class. Example:

public class FooManager
{
     public string Foo { get; private set; }
     public string Bar { get; private set; }

     private FooManager(string foo, string bar)
     {
         Foo = foo;
         Bar = bar;
     }

     public static FooManager MakeFooManager(string foo, string bar)
     {
         // Can do other checks here too.
         if(foo == null || bar == null)
         {
             return null;
         }
         else
         {
             return new FooManager(foo, bar);
         }
     }
}

Since a constructor is implemented, there is no way for anyone to create an instance of FooManager without going through MakeFooManager().