Using a struct purely for variable documentation

[ChayHawk]

I am just writing and playing around with some code and I wanted to have a word represent a number in the parameter list of my class object, my numbers are ints but if i wanted to use a float then I wouldn't be able to use an enum, so I created a struct and then initialized the variable in the parameter lists to keep things neater. Im wondering if this is ok to do. Everything works just fine but i've learned over the years that doesn't always mean it's correct practice.

Also I was wondering something about const. These variables in the parameter lists of these functions are declared as const:

void TakeDamage(const int& damageTaken);    void RestoreHealth(const int& restoreAmount);
    void UpgradeAttackPower(const int& upgradeAmount);
    void DisplayCharacterInfo(Character& character);

I was told to make these const by someone else. Now i know that const makes it so the variable cannot be changed, but the damageTaken variable changes so why make them const? why does it still work even though they are declared as const?

#include <iostream>
#include <string>
#include <vector>


using namespace std;


class Item
{
public:
    Item();


    string GetItemName() const { return itemName; }


private:
    string itemName{};
    int cost{};
    int healthRestored{};
};


class Character
{
public:
    Character(string charClass, int charHealth, int charMaxHealth, int charAttackPwr, int charMaxAttackPwr) :
        charClass(charClass),
        charHealth(charHealth),
        charMaxHealth(charMaxHealth),
        charAttackPwr(charAttackPwr),
        charMaxAttackPwr(charMaxAttackPwr) {}


    string GetCharClass() { return charClass; }


    int GetCharHealth() const { return charHealth; }
    int GetCharAttackPwr() const { return charAttackPwr; }
    int GetCharMaxAttackPwr() const { return charMaxAttackPwr; }
    int GetCharMaxHealth() const { return charMaxHealth; }


    void TakeDamage(const int& damageTaken);
    void RestoreHealth(const int& restoreAmount);
    void UpgradeAttackPower(const int& upgradeAmount);
    void DisplayCharacterInfo(Character& character);


private:
    string charClass{};
    int charHealth{};
    int charMaxHealth{};
    int charAttackPwr{};
    int charMaxAttackPwr{};
};




ostream& operator<< (ostream& os, Character& character)
{
    os << "Class Name: " << character.GetCharClass() << endl;
    os << "Health: " << character.GetCharHealth() << endl;
    os << "Max Health: " << character.GetCharMaxHealth() << endl;
    os << "Attack Power: " << character.GetCharAttackPwr() << endl;
    os << "Max Attack Power: " << character.GetCharMaxAttackPwr() << endl;


    return os;
}


void Character::RestoreHealth(const int& restoreAmount)
{
    if (charHealth + restoreAmount <= charMaxHealth)
    {
        charHealth += restoreAmount;
    }
    if (charHealth + restoreAmount >= charMaxHealth)
    {
        charHealth = charMaxHealth;
    }
}


void Character::TakeDamage(const int& damageTaken)
{
    if (charHealth > 0)
    {
        charHealth -= damageTaken;


        if (charHealth <= 0)
        {
            charHealth = 0;
            cout << "The " << GetCharClass() << ", was defeated." << endl;
        }
    }
}


void Character::DisplayCharacterInfo(Character& character)
{
    cout << character << endl;
}




//Create a struct to give values a name instead of just a confusing number. 
//Could have used an enum, but enums cant contain floats, so this fixes that potential issue.
struct Data
{
    float health{};
    int maxHealth{};
    int attackPower{};
    int maxAttackPower{};
};




int main()
{
    Data data;


    Character Knight("Knight", data.health = 100, data.maxHealth = 150, data.attackPower = 5, data.maxAttackPower = 5);
    Character Samurai("Samurai", data.health = 50, data.maxHealth = 100, data.attackPower = 7, data.maxAttackPower = 7);
    Character Marine("Marine", data.health = 200, data.maxHealth = 250, data.attackPower = 4, data.maxAttackPower = 4);


    //Debug
    cout << "--BEGIN DEBUG--\n" << endl;


    Samurai.TakeDamage(Knight.GetCharAttackPwr());
    Samurai.DisplayCharacterInfo(Samurai);


    Knight.RestoreHealth(1);
    Knight.DisplayCharacterInfo(Knight);


    cout << "--END DEBUG--" << endl;
    //End Debug


    return 0;
}

[jimblumberg]

Also posted here.

[laserlight]

You're basically creating an object merely to serve as documentation, and it really is just documentation as you could have just as easily written by mistake:

Character Knight("Knight", data.maxHealth = 150, data.health = 100, data.maxAttackPower = 5, data.attackPower = 5);

As such, there's a simpler solution to your problem. Comment your code:

Character Knight("Knight", /* health */ 100, /* maxHealth */ 150, /* attackPower */ 5, /* maxAttackPower */ 5);

If you want to make use of secondary objects to help you avoid mistakes while being self-documenting, then write a configuration class such that you can do something like this:

Character Knight(Character::Config("Knight").health(100).maxHealth(150).attackPower(5).maxAttackPower(5));

For example:

#include <iostream>
#include <string>
#include <vector>

using namespace std;

class Item
{
public:
    Item();

    string GetItemName() const { return itemName; }

private:
    string itemName{};
    int cost{};
    int healthRestored{};
};


class Character
{
public:
    class Config
    {
        friend class Character;
    public:
        explicit Config(const std::string charClass) : charClass(charClass) {}

        Config& health(int value)
        {
            charHealth = value;
            return *this;
        }

        Config& maxHealth(int value)
        {
            charMaxHealth = value;
            return *this;
        }

        Config& attackPower(int value)
        {
            charAttackPwr = value;
            return *this;
        }

        Config& maxAttackPower(int value)
        {
            charMaxAttackPwr = value;
            return *this;
        }
    private:
        string charClass{};
        int charHealth{};
        int charMaxHealth{};
        int charAttackPwr{};
        int charMaxAttackPwr{};
    };

    explicit Character(const Config& config) :
        charClass(config.charClass),
        charHealth(config.charHealth),
        charMaxHealth(config.charMaxHealth),
        charAttackPwr(config.charAttackPwr),
        charMaxAttackPwr(config.charMaxAttackPwr) {}

    string GetCharClass() { return charClass; }

    int GetCharHealth() const { return charHealth; }
    int GetCharAttackPwr() const { return charAttackPwr; }
    int GetCharMaxAttackPwr() const { return charMaxAttackPwr; }
    int GetCharMaxHealth() const { return charMaxHealth; }

    void TakeDamage(const int& damageTaken);
    void RestoreHealth(const int& restoreAmount);
    void UpgradeAttackPower(const int& upgradeAmount);
    void DisplayCharacterInfo(Character& character);

private:
    string charClass{};
    int charHealth{};
    int charMaxHealth{};
    int charAttackPwr{};
    int charMaxAttackPwr{};
};


ostream& operator<< (ostream& os, Character& character)
{
    os << "Class Name: " << character.GetCharClass() << endl;
    os << "Health: " << character.GetCharHealth() << endl;
    os << "Max Health: " << character.GetCharMaxHealth() << endl;
    os << "Attack Power: " << character.GetCharAttackPwr() << endl;
    os << "Max Attack Power: " << character.GetCharMaxAttackPwr() << endl;

    return os;
}


void Character::RestoreHealth(const int& restoreAmount)
{
    if (charHealth + restoreAmount <= charMaxHealth)
    {
        charHealth += restoreAmount;
    }
    if (charHealth + restoreAmount >= charMaxHealth)
    {
        charHealth = charMaxHealth;
    }
}


void Character::TakeDamage(const int& damageTaken)
{
    if (charHealth > 0)
    {
        charHealth -= damageTaken;

        if (charHealth <= 0)
        {
            charHealth = 0;
            cout << "The " << GetCharClass() << ", was defeated." << endl;
        }
    }
}


void Character::DisplayCharacterInfo(Character& character)
{
    cout << character << endl;
}


int main()
{
    Character Knight(Character::Config("Knight").health(100).maxHealth(150).attackPower(5).maxAttackPower(5));
    Character Samurai(Character::Config("Samurai").health(50).maxHealth(100).attackPower(7).maxAttackPower(7));
    Character Marine(Character::Config("Marine").health(200).maxHealth(250).attackPower(4).maxAttackPower(4));

    //Debug
    cout << "--BEGIN DEBUG--\n" << endl;

    Samurai.TakeDamage(Knight.GetCharAttackPwr());
    Samurai.DisplayCharacterInfo(Samurai);

    Knight.RestoreHealth(1);
    Knight.DisplayCharacterInfo(Knight);

    cout << "--END DEBUG--" << endl;
    //End Debug

    return 0;
}

Now, the code is not only self-documenting, but also ensures that you don't mix up the order of arguments. What it doesn't do is enforce at compile time that all of the configuration parameters are provided (i.e., you can enforce this at run time, but not really at compile time with this approach).

EDIT:
coder777's idea in that other thread does enforce at compile time that all of the configuration parameters are provided because it just names specific types and values while retaining the original constructor, but for ease of use it also requires you to declare all these specific values in advance, rather than at the construction of the object. This could work very well if you only have a limited number of what are effectively subtypes of the Character type (but if so, why not use a simple factory instead?), but it won't work so well if you want more dynamic Character object creation.

[ChayHawk]

Also posted here.

And? I like having multiple perspectives, I often post on 3 or 4 different programming forums, I often find people on the same forum generally have a certain way of programming than others so the people on each forum provide different answers and solutions.

@laserlight, Interesting solution, i'll look this over. I thought of using just comments but I thought maybe having actual code document things would be easier and neater. as for the other forums code, I feel like creating namespaces just for documentation is overkill, but maybe i'm wrong, I've only used namespaces a few times and there are gaps in my C++ knowledge.

I didnt even think about the argument orders being able to be mixed up.

This could work very well if you only have a limited number of what are effectively subtypes of the Character type (but if so, why not use a simple factory instead?), but it won't work so well if you want more dynamic Character object creation.

I always like to create my code as if more stuff will always be added in an attempt to future proof it, unless I know for absolute 100% certainty it will not/not abale to be extended further.

Thanks for the help, I'll play around with the code.

[Salem]

Here's what cross-posting means to us.
How To Ask Questions The Smart Way
How To Ask Questions The Smart Way

Cross-posters tend to get ignored when there MO becomes apparent.

Because it's a waste of OUR time answering questions which often garner the same answers elsewhere.