2

Are there any official C++ recommendations that concern with the amount of information that should be disclosed in a method name? I am asking because I can find plenty of references in Internet but none that really explains this.

I'm working on a C++ class with a method called calculateIBANAndBICAndSaveRecordChainIfChanged, which pretty well explains what the method does. A shorter name would be easier to remember and would need no intellisense or copy & paste to type. It would be less descriptive, true, but functionality is supposed to be documented.

5
  • Why someone will want to remember the method names? It's always handy in any decent IDE>
    – iammilind
    Jan 10, 2013 at 11:28
  • You should read clean code Jan 10, 2013 at 11:29
  • 2
    its a matter of preference and quite a lot of debate. there's no clear cut "right" answer here.
    – Oren
    Jan 10, 2013 at 11:29
  • "Official"? Your boss's recommendations are official. The C++ standard doesn't advise on coding style and it doesn't care what you call your functions as long as you don't use reserved names. Jan 10, 2013 at 11:54
  • No, f(x) and g(y) is all real men need.
    – Bo Persson
    Jan 10, 2013 at 12:08

6 Answers 6

12

calculateIBANAndBICAndSaveRecordChainIfChanged considered to be a bad function name, it breaks the rule of one-function-does-one-thing.

Reduce complexity

The single most important reason to create a routine is to reduce a program's complexity. Create a routine to hide information so that you won't need to think about it. Sure, you'll need to think about it when you write the routine. But after it's written, you should be able to forget the details and use the routine without any knowledge of its internal workings. Other reasons to create routines—minimizing code size, improving maintainability, and improving correctness—are also good reasons, but without the abstractive power of routines, complex programs would be impossible to manage intellectually. You could simply break this function into below functions:

CalculateIBAN
CalculateBIC
SaveRecordChain
IsRecordChainChanged

To name a procedure, use a strong verb followed by an object

A procedure with functional cohesion usually performs an operation on an object. The name should reflect what the procedure does, and an operation on an object implies a verb-plus-object name. PrintDocument(), CalcMonthlyRevenues(), CheckOrderlnfo(), and RepaginateDocument() are samples of good procedure names.

Describe everything the routine does

In the routine's name, describe all the outputs and side effects. If a routine computes report totals and opens an output file, ComputeReportTotals() is not an adequate name for the routine. ComputeReportTotalsAndOpen-OutputFile() is an adequate name but is too long and silly. If you have routines with side effects, you'll have many long, silly names. The cure is not to use less-descriptive routine names; the cure is to program so that you cause things to happen directly rather than with side effects.

Avoid meaningless, vague, or wishy-washy verbs

Some verbs are elastic, stretched to cover just about any meaning. Routine names like HandleCalculation(), PerformServices(), OutputUser(), ProcessInput(), and DealWithOutput() don't tell you what the routines do. At the most, these names tell you that the routines have something to do with calculations, services, users, input, and output. The exception would be when the verb "handle" was used in the specific technical sense of handling an event.

Most of above points are referred from Code complete II. Other good books are Clean Code, The Clean Coder from Robert C. Martin

13
  • 2
    The function I mentioned is used 8 times in code. Do you think it would be a good idea to split every function call with four ones (and retype the code)?
    – GOTO 0
    Jan 10, 2013 at 11:37
  • 1
    With a bit more domain knowledge you recognize 2 functions: CalculateBicAndIban (Bic identifies the bank holding an account, Iban the individual account) and UpdateRecordChain (to update an outdated record chain, you need to save it). However, these two operations are fairly independent.
    – MSalters
    Jan 10, 2013 at 11:43
  • 4
    If you wrap it up as a new function then you need a name for the new function. In effect you've refactored the existing function so that it works by calling 4 other functions in turn. Which is all very well but unrelated to the issue of whether the existing function name is appropriate. Jan 10, 2013 at 11:58
  • 1
    @blitz: also "DoABandC" can call DoA, DoB and DoC, but neverless DoABandC has to exist, especially if you have do call them always in that order and hundredths of time, with no risk to forget something somewhere in the hundredth of copy paste. It is the "Don't repeat yourself" principle. So how do you call DoABandC? Jan 10, 2013 at 12:10
  • 2
    For an example from real life, I did work experience in a solicitor's office (in an era when people used paper). Some time after a case ended you needed to take the file, get sign-off from accounts, and put it in archive storage. Unsurprisingly, the solicitors did not refer to this as "getting accounts to check the billables against invoices and invoices against payments received and then going to the archive room and placing it alphabetically by client name into the correct filing cabinet". They called it "deading", as in "can you dead those files please?". Jan 10, 2013 at 12:53
4

To answer the direct question, I don't think function names need to be memorable. It's nice if they are, but like you say this stuff is supposed to be documented. I can look it up.

calculateIBANAndBICAndSaveRecordChainIfChanged is too long for my taste. Aside from the inconvenience of having to c/p or auto-complete to even use them, my fear with long function names is that I don't read them properly either, so names with similar "shapes" start to look confusingly similar to one another.

So I would advise looking for a shorter name. There must be some reason why these operations (calculating two things, and conditionally saving a record chain) have been grouped together. That reason isn't described in the question, it lies somewhere in the specification or the history of your project. You should identify that reason and look to it for a more succinct function name.

When naming a function you can also consider what reasons[*] the function might change in future. Why are there two things (IBANA and BIC) that are calculated at the same time? What is the relationship between them? Can you identify the reason for doing both at once and then saving?

For example: they are the "acronyms" for this object, it's common to want to recalculate the acronyms all at once, and if you recalculate then naturally the changes need saving. Then call the function refreshAcronyms. Maybe there will be a third acronym in future.

For another example: what callers really want is to save the object if changed, and it's an additional chore that to preserve integrity of the stored data, I must always recalculate the IBANA and the BIC before saving. In that case, all the rest is necessary precursors to saving, so I can call the function saveRecordChain. Users of the public interface just need to know that the save function does what needs to be done. There might be a serializeToFile() function in the private interface that saves if changed without doing the extra stuff.

[*] I say "reasons" plural, but Robert C Martin defines the "single responsibility principle" to be that there is only one possible reason to change a well-designed function.

1
  • +1! Definitely better than the current top answer (billz'). This is, in the end, all about SRP: the function name should describe its functionality, not its guts, because the guts change with time. Jan 10, 2013 at 12:38
2

Ideally one method should do only one thing. And your method name should reflect what it does (that one thing), then only your program become readable.

2

It''s a matter of personal preference although I would think that calculateIBANAndBICAndSaveRecordChainIfChanged is too long and therefore difficult to read and code with (unless you're using a smart editor that can auto-complete)

Two further points:

  1. The function needs to be broken down into smaller parts, as other posters have suggested.
  2. There's no law against commenting your headers to give a more detailed description of the function there so you don't have to build every aspect of its functionality into the name.
1

You read and write too many methods over the course of your career to remember their names. Most programmers would need to look up a name of a function from their language's standard library, let alone names of functions that their or their team developed! The most memorable function name would be of no use to someone maintaining your code and seeing the call for the first time. Moreover, good chances are that in six months you wouldn't remember it either!

That is why I recommend going for descriptive names first, and not worrying about the ease of memorization: after all, IDEs with intellisense are not going away any time soon (and they were introduced for a good reason - to address our memory limitations).

0

For personal interaction that would be enough and useful, but any way after completing the app you have to re-factor every function name to exactly what they intend to do. And if working in a group or in company make it sure that function name reflects what its functionality is.

And in your eg function name i may name it like: saveRecordWithRespctToIBANandBIC()

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.