Question

I am beginner at C++, the homework ask us to document our code (preamble, and with the function’s pre-post conditions). I am wondering how do they apply to my Student class?

In particular, what exactly is preamble mean? And for my get methods, what are the pre and post conditions? I have a feeling they are really for more advance’s function (these who changes the value of the data)?

class Student:
{
public:
    // Constructor for the student class, require 4 parameters
    // In the order of string (first name), string (last name), 
    // integer (student ID), string (major)
    Student(string myFirstName, string myLastName, int myID, string myMajor)
    {
        firstName = myFirstName;
        lastName = myLastName;
        uid = myID;
        major = myMajor;
    }

    // Get function for the student's first name
    // Return the student's first name
    string getFirstName()
    {
        return firstName;
    }
    .....

private:
    string firstName; // Student's first name
    string lastName; // Student's last name
    int uid; // Student's ID number in a number format
    string major; // Student's major
};

Answer 1

preamble is a source code comment appearing before the function that documents its behaviour, normally in a way that a tool like doxygen can automatically create useful documentation from it.

A good policy for documentation is to document everything that isn’t obvious and nothing that is. On that basis, I’d say your getXXX() have no pre- or post-conditions worth documenting. Something like “must be called on a properly constructed object” is just a waste of the reader’s time, as is a post-condition like “the caller will have received a copy of the student-specific XXX data”. Don’t do it! The question of whether the values can legally be empty strings is one for the constructor (or may even be a class invariant – something the class maintains as true, for instance by having the constructor throw if a value is empty and by not providing functions that wipe out the values), not for the get function documentation.

Similarly, your comments for firstName, lastName and major add absolutely no value, but your comment for uid does add value – documenting a requirement for a string format! From that I can tell you’ve made a mistake, as the field is an int, and there’s something to investigate and correct. But more generally, say you had a string type – a comment might usefully communicate some restrictions on the format of the id, say that these ids relate to some other API or source, give an example etc.

More generally, pre-conditions aren’t only for mutator (data changing) functions. For example, a function day_for_date(int year, int month, int day) that tells you what day of the week a particular date falls on may have a pre-condition that year/month/day does actually describe say a valid date between 1000 and 3000 A.D.. That’s nasty, but it means if you’ve already checked that somewhere the function call doesn’t waste time re-verifying it. In Defensive Programming style (which IMHO tends to make for more robust code) you would tend not to make that a precondition; instead, accept redundant verification as a net win (though you may provide explicit options to disable it if the caller needs the performance), and document an exception or error outcome should the date not meet expectations. The difference is that a precondition is something the caller must guarantee for the function to operate as documented, where-as in defensive programming you generally let the caller try something and have a defined/documented manageable behaviour – a change in state, return value or error reported in a predictable way – for as broad a range of prior states and inputs as is practical.

Post-conditions only make sense for mutators: whatever could be asserted about the state after the call to a non-mutating accessor must have been true beforehand – it might be a class invariant.