Protect Object State with Constructors and Methods

A session starts at twenty-five minutes. Adding ten should work; adding negative five should leave the total alone. Where must those rules live if callers cannot be trusted to check them?

Predict the two Boolean results and the final total, then run this complete program.

using System;

StudySession session = new StudySession("  C#  ", 25);
Console.WriteLine(session.TryAddMinutes(10));
Console.WriteLine(session.TryAddMinutes(-5));
Console.WriteLine($"{session.GetTopic()}: {session.GetMinutes()}");

class StudySession
{
    private string topic;
    private int minutes;

    public StudySession(string topic, int minutes)
    {
        if (string.IsNullOrWhiteSpace(topic))
        {
            throw new ArgumentException("Topic is required.", "topic");
        }
        if (minutes < 0)
        {
            throw new ArgumentOutOfRangeException("minutes");
        }

        this.topic = topic.Trim();
        this.minutes = minutes;
    }

    public string GetTopic()
    {
        return topic;
    }

    public int GetMinutes()
    {
        return minutes;
    }

    public bool TryAddMinutes(int extra)
    {
        if (extra <= 0 || extra > int.MaxValue - minutes)
        {
            return false;
        }

        minutes += extra;
        return true;
    }
}

Follow the accepted change

The output is True, False, then C#: 35. The constructor trims the topic and rejects an invalid starting state. TryAddMinutes rejects a later unsuitable request by returning false, leaving the object usable.

The private field can be accessed inside its declaring class. The public methods are the operations available to callers. this.minutes means the current object's field; minutes alone names the constructor parameter there. The Get methods expose values without exposing assignments. The next lesson replaces that reading syntax with properties.

Private access alone is insufficient: a public method could still write an invalid value. Search for assignments to the field. Initialization and the accepted update are the only routes, and both have checks.

The capacity check uses int.MaxValue - minutes before adding. Since the existing total is nonnegative, the subtraction is safe. An extra amount larger than that remaining capacity is rejected before it can overflow. Zero is deliberately rejected too: this method accepts positive additions.

Build a goal that rejects the whole request

Create StudyGoal with a positive target and an initially zero completed total. TryComplete accepts only a positive amount that will not exceed the target. A rejected request changes nothing.

Use a target of sixty and try twenty, fifty, then forty. Write the completed total after each call before implementing the method. Your checks must prove that the rejected fifty does not consume any of the remaining goal.

Hint: compare the request with the remaining capacity before changing completed.

Check your solution

Expect True, False, True, then Completed: 60. The last request reaches the target exactly.

using System;

StudyGoal goal = new StudyGoal(60);
Console.WriteLine(goal.TryComplete(20));
Console.WriteLine(goal.TryComplete(50));
Console.WriteLine(goal.TryComplete(40));
Console.WriteLine($"Completed: {goal.GetCompleted()}");

class StudyGoal
{
    private int target;
    private int completed;

    public StudyGoal(int target)
    {
        if (target <= 0)
        {
            throw new ArgumentOutOfRangeException("target");
        }

        this.target = target;
    }

    public int GetCompleted()
    {
        return completed;
    }

    public bool TryComplete(int amount)
    {
        if (amount <= 0 || amount > target - completed)
        {
            return false;
        }

        completed += amount;
        return true;
    }
}

Point to the guard that preserves the total after rejection. Throwing during invalid construction and returning false for an ordinary rejected update are choices for this model; they are not rules every API must follow.

Reference: Microsoft: constructors.