13

I am developing an open-source academic software package that includes several functions from literature. These functions are not always given a name by the original authors and so the convention is to refer to them by the author's name. For example, consider the hypothetical Smythenson-Johansen function.

In my software, the documentation lists the complete name and provides full references, but the function name is generally abbreviated as (for example)

smythjo()

I am generally trying to balance (i) concision, (ii) readability and consistency, (iii) uniqueness from other functions, and (iv) clarity.

A colleague suggested that abbreviating names like this could be potentially problematic, or disrespectful to the authors. This had never occured to me, as I certainly wouldn't be offended by somebody abbreviating my name in code, but I'm realizing that my colleague may have a point and I should consider this more carefully.

Questions

  • Could this be considered inappropriate or unprofessional?
  • If so, is it acceptable to use initials, like sj()? This is less descriptive/readable, but less arbitrary.
  • Are there any other solutions before I (and any future users) have to look up the spelling for smythenson_johansen() every time they want to use a function?
Improve this question
2
  • 2
    You'll see "bool" all over the place. Granted, he's no longer around to be offended. Commented Jan 24, 2025 at 13:22
  • You could chicken out and export the same function under multiple different names from your package, forcing the choice on the users of the library. Of course the downside is that this could lead to inconsistent/convoluted codebases and bad memorisation. Commented Jan 25, 2025 at 18:46

6 Answers 6

Reset to default
49

There is a long history of doing this, dating back to the time of early versions of Fortran where function names could only have 6 characters and the first character was often used to denote the data type of the value returned. For example, the IMSL library abbreviates the "Bessel J_0" function as BSJ0, and if you follow the table at the left of that page, you can see that that is true for any number of other names as well. Many other libraries have been doing the same over the decades. As a consequence, I think that everyone who has been doing computations for a while will understand the approach you are taking, and nobody should be offended.

There is of course an unasked question whether that is a useful approach. My take on that is no. The time when function names had to fit into six characters has, for all practical purposes, passed several decades ago. (For example, Fortran 90 no longer has this restriction, and I don't know any other languages that did not allow long function or variable names in the 1980s either.) The issue with short names is that they are hard to memorize. For example, dgemm is a widely used function name that stands for d=double precision, ge=general matrix, mm=matrix-matrix product. If you know how to decode this, it's easy -- but if you're not an expert in the BLAS library that has this function, you wouldn't be able to guess what the function does if you don't know the system.

As a consequence, my recommendation (and practice) these days is to spell out names and words in function and variable names. You should be programming with a system that has autocomplete functionality anyway, so spelling smyth+Ctrl-Space or whatever else your system uses should complete to the expanded name -- that's not much more typing than smyjo, but it's self-explanatory in the code. The latter point is important because you need to remember that we write code for human readers, not for computers.

Improve this answer
1
  • 3
    "There is of course an unasked question whether that is a useful approach." - If the target audience has internalized the abbreviations being used, abbreviated function names can make it easier to read code by allowing the author better control over line breaks. Often, it is more important that such names be easy to recognize than that they be easy to memorize. I'll further note that it is rather common for mathematics papers to use one or two letter variables for concepts they've introduced in their own paper, so the idea of abbreviated names is often uncontroversial. Commented Jan 24, 2025 at 14:40
8

I doubt that anyone would object. However, to avoid several issues, you should probably include a citation in a comment, giving the full recognized name and the source. This avoids possible issues of plagiarism and such.

But, having made it clear, an abbreviation should be fine. Even sj, though I'd prefer something a bit more intuitive like smythjo.

Improve this answer
1
  • This would be a great opportunity to learn Doxygen or another documentation tool. You can attribute the function in your comment, include any other details, links, etc, and have Doxygen build a documentation package that can then be hosted as a self-contained website. Commented Jan 23, 2025 at 17:01
7

Bessel, Legendre, Hamiltonian, Fermi, Pearson and above all Green - there are plenty of names used in science and functions/methods/tests are routinely referred to by the name. However, there are a few points to consider:

  • Using the name of a living person, unless it is already a well-established convention in the field, may be seen as flattery - by this person and others.
  • Abbreviations may unintentionally turn out to sound weird or even insulting, especially when working in an international environment.
  • Using names is ambiguous - a fruitful scientist might have produced several results associated with their name.
  • Using names is less user-friendly than a name that unambiguously points to the content of the method or how it differs from other methods.

My suggestion would be to use more telling names, referring to the particularities of the procedure employed. Even better, if there is a systematic naming convention for different functions, so that one can se relation between them. In the same time in function description/help/comments/documentation I would name the authors and even a citation to the relevant paper.

Improve this answer
0
5

A colleague suggested that abbreviating names like this could be potentially problematic, or disrespectful to the authors.

This is a ridiculous concern, to the point where I would seriously question the judgment of anyone who raised it. I'm reminded of the professor in this question who raised a similarly silly objection.

I am generally trying to balance (i) concision, (ii) readability and consistency, (iii) uniqueness from other functions, and (iv) clarity.

Yes, these are the correct criteria, and you should use exclusively these criteria when deciding on your nomenclature. People will have different opinions about whether smyth_jo() is better or worse practice than smythenson_johansen() (c.f., the other answers), but neither choice is "inappropriate or unprofessional."

Improve this answer
2
  • 2
    I dunno, there's somethings that could be rude, calling it dick_smith() which Richard Smith goes by Rick, or even abbreviating "Smythenson" to "Smyth" - potentially confusable with a different person. Commented Jan 23, 2025 at 19:42
  • 6
    well, there are always ways to go too far, calling it that_ass_holes_formula() is probably unwise. But that's not the scenario OP describes. Commented Jan 23, 2025 at 20:26
3

As a coder, it really depends on the function name length. Contrary to Wolfgang's answer, it's entirely possible to be working with an IDE which isn't aware of all the libraries available, especially in the context of embedded software. You should expect users to have to type it. And even with auto-completion, very long function names can be a problem for it, where the IDE may only be able to show part of the name due to window size restrictions.

I don't see your "long" name being inconvenient. If you had four hypothetical authors' names, you might need to do something about it though.

Improve this answer
8
  • 5
    If your IDE can't correctly autocomplete, you're using the wrong tool. Long names were a bigger problem when we only had 80-character-wide terminal windows. These times are gone for at least two decades already. Every screen you work on these days can comfortably show 100 or more characters. It's your loss if you don't make use of this. Commented Jan 23, 2025 at 14:22
  • 1
    @WolfgangBangerth Of course, but there are limits. If someone gives me a 50-character function name, that'd be using a significant chunk of any IDE window. If there's a really good reason for it, that's fine. If there isn't a good reason for it, they could do better. As for the IDE, the issue isn't whether the tool is capable of autocompletion, it's whether the tool is aware of all the libraries you'll be building with. Unless you're only ever using Visual Studio with standard libraries, this will always be a problem. Commented Jan 23, 2025 at 14:50
  • Well, sure, 50 characters is too long. But how often does that happen? As for IDEs: In all reasonable languages, you either have to #include header files, or import libraries, to use names. IDEs these days deal with this just fine. I don't see that as a reason not to use long names. Commented Jan 23, 2025 at 17:03
  • @WolfgangBangerth Like I said, there's limits on what's OK. I'm glad you now agree. As for IDEs, you clearly have never tried setting this up for yourself for some embedded system, because it's painful, and generally life's too short. For sure if your coding only runs on a PC and builds in Visual Studio then that's probably true, but there's more to software than just that. Commented Jan 24, 2025 at 0:38
  • 3
    @WolfgangBangerth Autocomplete or not, would you rather read probability_density_function = 1.0 / sqrt(2.0 * PI * standard_deviation * standard_deviation) * exp(-(sample_point - population_mean) * (sample_point - population_mean) / (2.0 * standard_deviation * standard_deviation)) or would you prefer to read pdf = 1.0 / sqrt(2.0 * PI * stdev * stdev) * exp(-(x - mean) * (x - mean) / (2.0 * stdev * stdev)). Sometimes brevity is clarity. Commented Jan 24, 2025 at 15:26
2

Long function names are fine in principle. One aspect I haven't seen mentioned in the other answers is - it's nice to be able to type perhaps the first three characters and then press Tab to autocomplete. It's inconvenient needing to type many characters before autocomplete gets it, or needing to scroll down the autocomplete box.

Therefore, the name smythenson_johansen is fine in isolation. It's fine if the other function names are davies_russel and hamilton_mellings, because in all cases the first three letters + Tab will autocorrect to the correct function.

However, if the function names are:

smythenson_johansen smythenson_johansen_modified smythenson_johansen_ditchford smythenson_johansen_multidimensional smythenson_johansen_inverse

Then this is a really bad naming convention that either needs to be rethought or broken into namespaces.

Improve this answer

You must log in to answer this question.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.