Coding convention

[George]

Ok, I have two C++ classes; call them Foo and Bar. Foo is given to me as input (actually I create it to wrap my input) each iteration and I use it to update a persistent instance of Bar. Is there any convention for which class should contain the method to perform the update?

void Foo::update(Bar) const

-or-

void Bar::update(const Foo)

It's just a philosophical question, because in the case that inspired it there turned out to be performance implications

[Peijen]

Foo changes the state of Bar therefore Bar::update(const Foo)

[Jonathan]

I agree with Peijen. You can use Foo a lot of places. Foo might update Baz later. Or Bar2.

[George]

I'm not disagreeing, but my use of the word "update" may have been misleadingly generic. It's a very specific update, and while Foo can update other objects, by domain-specific definition, it can only do this particular action to Bars. I did end up putting it in Bar, but for reasons of expediency and misinterpretation.

Interestingly, the same code contains a case where I made the reverse decision. Bar is actually a list of BarElements. Periodically, we scan through Bar for BarElements with certain properties and fill in a Report structure for each. So I have a BarElement::generateReport(Report &) const method. Is this bad? It pretty much has to be that way, since the Report structure's definition is not under my control. Also, I don't want to have to publically expose the dozen properties of BarElement when the Report is already entirely public (it's just a struct).

[bob]

I would agree that you want Bar::Update(const Foo&). I use my Update functions to mean "Update this object based on these parameters". With a function named "GenerateReport", I would probably return a Report object; whereas a function that modifies the report would use a different verb, as in ModifyReport or UpdateReport.

I don't think the second half of the paragraph conflicts with the first, because UpdateReport has a different grammatical direct object than Update[Yourself]. I find APIs based on rules of a spoken language to be much easier to use.

[bob]

Of course UpdateReport(Report&) brings you almost right back to where you started with your original question!

[George]

Of course UpdateReport(Report&) brings you almost right back to where you started with your original question!

Yes. Using the two different approaches one right after another was what started me wondering about the convention. It seems like the consensus is that there is no absolute preference, but rather the preference is based on the specific vocabulary and grammar used in the method name.

The original method is not and never was named "update". I just used that term to avoid having to explain the vocabulary needed to understand the domain-specific method name.

[bob]

Name all important API functions in German. If working with a German-speaking development team, learn Esperanto.

[George]

Actually, even better is to write encode all of your source files in unicode so that you can use non-ASCII characters. Then name your stuff with asian characters.

Along the same lines, you may be able to include non-printable characters in your code, depending on how tolerant your compiler is. Name all your variables with one printable character and use a combination of non-printable characters to differentiate between them.

One of my coworkers is misusing a combination of Metrowerks Codewarrior, CVS, Tortoise, and some Unix editor in a way that causes some files he commits to the repository to replace all \r\n's with \r\n\n. It takes a hex editor to fix them.