41

Don't be afraid to make a name long. A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment.

Robert C. Martin

Did I understand Clean Code right? You put the whole information that you would put into a comment into the class/method/... name. Wouldn't that lead to long names like:

PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorComments
PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorDescriptions
  • 17
    I suspect that a lot of the information of those variables would be encoded in their type, so in a realistic scenario you would only need to label the parts that distinguish them – Alexander - Reinstate Monica Apr 29 at 23:34
  • 44
    Argh! Ocular trauma. Think of it like writing a story. How often do you want to see said Penny from over the road, born in the blue house, friend to Bob. If you are in that context Penny is sufficient, or maybe Penny White if there are two possible Pennies around. Or may Bob's friend Penny when we are already talking about Bob. Chances are this class is already in the UI, therefore it is already graphical. Its probably in the namespace for the editor so how about: CommentsReloader and DescriptionsReloader? – Kain0_0 Apr 30 at 0:14
  • 17
    @TomatenSalat: The point is that ridiculously long names do not make up for good comments and documentation. "Do not be afraid to use a long name" is not the same as "try to avoid comments by making your names longer". – Martin Maat Apr 30 at 7:44
  • 2
    Who's the human audience for your code? Your future self, for one. Your co-workers and future co-workers for another. Write the code for the audience. Matt Mullenweg (WordPress) likes to say "code is poetry." Sure, but don't write it so somebody needs a PhD in postmodern semiotics to understand it. Imitate Socrates, not Aquinas. – O. Jones Apr 30 at 12:01
  • 3
    Be afraid! Reading code with those long names is a nightmare! Especially when several names have the same pattern and/or common words. I prefer reading a comment and keep in mind what that means, then being able to go through lines of code easily. A code has a spirit, people using those long names had never had to read other people's codes. – Alexis May 1 at 23:20

10 Answers 10

8

You have to take everything in Clean Code together. I've read the book more than once. I frequently lend it to new developers on my team.

Yes, Martin does say you should prefer long, descriptive names over comments. However, he also advocates for the Single Responsibility Principle.

I've seen SRP defined a few ways, usually "a class or method should only have one reason to change", or "a class or method should do only one thing".

So, I tell my developers to write very descriptive names. I also frequently tell them that if the name of the method is getting too long, it is probably doing too many things.

If the name of the method is becoming unmanageable, consider if something needs refactoring.

I also tell my team to avoid the Incredibles Pattern. As we learned from Syndrome, "when everybody's special, nobody's special."

If every property or method of you class starts or ends with the same word(s), you can probably omit that word.

Assuming these are both members of one class, would the following make sense?

It looks like you have many PageReloaders, so we make a base class for the things all PageReloaders do.

abstract class PageReloader {
    //page reloader code
}

Next, the name indicates that being "used in the editor" is significant, so there must be other kinds of VectorGraphicsReloaders.

abstract class VectorGraphicsReloader : PageReloader{
    //vector graphics code
}

Finally, we get to the EditorGraphicsReloader, which is a VectorGraphicsReloader that does something specifically for the editor.

class EditorGraphicsReloader : VectorGraphicsReloader{
    //editor code
}

Within one of these class we should have two properties:

public string Comments { get; set; }
public string Description { get; set; }

The class these properties belong to depends on whether they are unique to the editor, vector graphics, or common to all page reloaders.

| improve this answer | |
  • The link between names and SRP is really important here I think! I often tell my colleagues (and myself) "if you're struggling to come up with a name for something, maybe it's not a single thing". – IMSoP May 1 at 22:01
  • I think that this was a nice try to map the complexity to the class structure, but in your example you changed the meaning to a less complex one. I still think that yours is still the best solution, to refactor the class, instead of using a long name. – TomatenSalat May 6 at 7:15
150

Yes, you understand Clean Code right, but your examples are quite a bit over the top.

Here is what you start with:

PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorComments 
PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorDescriptions

A "Page Reloader" presumably reloads pages, so the "Pages" part is redundant. This leaves you with:

PageReloaderForDisplayingVectorGraphicsThatAreUsedInTheEditorComments 
PageReloaderForDisplayingVectorGraphicsThatAreUsedInTheEditorDescriptions

Pages are always displaying stuff, so the Displaying part is redundant, too. This leaves you with:

PageReloaderForVectorGraphicsThatAreUsedInTheEditorComments 
PageReloaderForVectorGraphicsThatAreUsedInTheEditorDescriptions

In English, constructs like this-that-is-used-in-that can be reworded as that-this. For example, coloring-that-is-used-for-food is food-coloring. Applying this rule, leaves you with:

PageReloaderForEditorCommentsVectorGraphics 
PageReloaderForEditorDescriptionsVectorGraphics

Also in English, constructs like this-for-that can be reworded as that-this. For example, bottle-for-water can be reworded as water-bottle. Applying this rule, leaves you with:

EditorCommentsVectorGraphicsPageReloader
EditorDescriptionsVectorGraphicsPageReloader

And then of course there may be other shortcuts you can apply.

For example, in your system you probably don't have many kinds of reloaders. You probably only have page reloaders, so this would leave you with:

EditorCommentsVectorGraphicsReloader
EditorDescriptionsVectorGraphicsReloader

Also, when you speak of 'vector' in your system, it may be fairly clear that you are speaking of 'vector graphics', so this would leave you with:

EditorCommentsVectorReloader
EditorDescriptionsVectorReloader

... and I think that these are some pretty good realistically long names.

| improve this answer | |
  • 25
    Also, some of that information could be in the name of a shared VectorReloader base class, or perhaps EditorCommentsReloader is a variable of type VectorReloader. – Robin Bennett Apr 29 at 11:32
  • 15
    And now you have (relatively) short enigmatic names instead of long descriptive ones. – Jacob Raihle Apr 29 at 13:33
  • 31
    @JacobRaihle Well, I think the alternative is something like CRldr and DRldr. Those are short enigmatic names. With that in consideration, I think something like EditorCommentsVectorReloader is still reasonably descriptive. (Though to be fair, I have not read the book.) – David Z Apr 29 at 20:53
  • 16
    @TomatenSalat That depends. If all throughout the codebase, everything is either VectorThis or RasterThat, it will be pretty understandable. If there is a vector algebra library included in the mix, then indeed VectorGraphics would be necessary. – Angew is no longer proud of SO Apr 30 at 6:51
  • 8
    @TomatenSalat, once names reach over 70 characters and over 20 syllables, I'm quite sure that my motivation for contracting those names is to enhance readability and bringing people in, not keeping people out! The advice your link gives concerns prose within scientific papers, where the purpose is typically to explain at length something that is unfamiliar or contentious, and economy with characters or syllables would not be expected. If your program requires such detailed explanation, then it would be done in documentation, not in the naming scheme. – Steve Apr 30 at 10:21
26

No, Uncle Bob is not saying that.

There is no part in his book saying that you have to put ALL COMMENTS in the class name, "the whole information" that you mentioned.

Probably you don't need a specific "PageReloader for Pages Displaying Vector Graphics etc etc" and should use the same PageReloader for all kind of pages.

In his book there are a lot of examples of what he exactly means with "replacing short enigmatic names by descriptive meaningful ones".

| improve this answer | |
  • 8
    Uncle Bob is not saying that, but it is the natural conclusion by some for the "some comments are bad; thus never ever write a comment" narrative. – Peter Mortensen Apr 29 at 22:20
  • 3
    @PeterMortensen Natural conclusion? OP has mixed two recommendations in one: meaningful names and no comments. It doesn't come so natural to me such conclusion: Ey, let's kill two birds with one stone. Why not? – RubioRic Apr 30 at 14:35
15

There is always a balance to be struck. Usually when software pundits speak, they are addressing a commonly understood problem of their time and place.

If names are so non-descript and enigmatic that they require explanation - like using f, g, and h, as the parameters of a method - then in the first place these should be elongated and made more descriptive.

There was a period when it was considered a significant problem for programmers to be habitually using overly-short names (often a random letter), and things would be radically improved simply by using a descriptive word or two.

Nowadays, the opposite problem is often observed. Programmers using unnecessarily verbose names, often a mangling of highly general terminology that is not especially descriptive of anything.

An example of the latter which most recently caught my eye was "ApplicationServices" - I couldn't immediately see how this was more descriptive than "ProgramTools", "CodeStuff" or even "AppSvcs".

"VectorGraphics" could arguably be reduced to "LineArt" without any loss of meaning, but even the abbreviation "VectGfx" would probably be quite enough.

So the principle of making names descriptive should not be read as meaning make names as long as possible. It's about using names that contain a high information density.

An element of that still involves being economical with syllables and characters, and relying on implied knowledge, such as a good command of the English language, and familiarity with general computer concepts.

| improve this answer | |
  • 6
    what does Gfx stand for? Graphic effects? Global effects? Isn't that "cute"? – TomatenSalat Apr 30 at 6:58
  • 8
    I think you'll be hard-pressed to find a programmer who would think Gfx stands for "global effects". – John Go-Soco Apr 30 at 7:30
  • 6
    @Steve why invent new words that not all people would understand when there are already existing ones that describe the real thing with 100% certainty? Imagine it was your first day at work and you have never done anything with Graphics. Using abbreviations just burns money. – TomatenSalat Apr 30 at 11:43
  • 3
    I didn't think it stood for "global effects" but I wouldn't have guessed "graphics" either – matt freake Apr 30 at 12:12
  • 1
    @TomatenSalat, why invent new names? Because 70 characters is too long, it's as simple as that. – Steve Apr 30 at 12:55
10

I agree with this answer https://softwareengineering.stackexchange.com/a/409460/262662 by Mike Nakis, but there's more.

Additionally, you can namespace and group some of this. such as

PageReloaders.EditorCommentsVector
PageReloaders.EditorDescriptionsVector

Then if you had more variables with equally long names, you could (only in short functions/blocks)...

Reloaders = Utilities.Reloaders.PageReloaders;
Reloaders.EdtiorCommentsVector.doSomething(); // small scope only.
// equivalent to...
Utilities.Reloaders.PageReloaders.EdtiorCommentsVector.doSomething();

// And with prettier, so long as the segments are within about 40 characters, it doesn't matter.  As it will look like this:
ReallyLongPath
  .filledWithLongStrings
  .JustToGetTo
  .Utilities
  .Reloaders
  .PageReloaders
  .EditorCommentsVector
  .doSomething();

Update

If I had to actually come up with my own names, based on the original, instead of Naki's answer, I would use the following.

PageReloaders.VectorGraphicsPages.EditorComments
PageReloaders.VectorGraphicsPages.EditorDescriptions

Or maybe

PageReloaders.EditorComments.WithVectorGraphics
PageReloaders.EditorDescriptions.WithVectorGraphics

But honestly, it depends on how much stuff you've got going on. If you really need a different pageReloader for editorComments vs editorDescriptions, or a different pageReloader for vectorGraphics pages vs normal? pages vs plainText pages, then you gotta do what you gotta do. If you don't have that much stuff, like if any page might or might not have vector graphics, just go with PageReloaders.EditorComments. Do NOT be afraid to change your variable names as a project grows. And Do NOT use stuff like pgrldr.VGraph.EtrCmnt to try to get shorter variable names. Just don't do it. The goal is to lower the amount of brain strain on future developers (including yourself) when trying to figure out what you did the first time around.

End Update

I believe what Robert C. Martin was actually referring to was the following:

<!-- We actually had this in our codebase -->
<button class="btn-submit pers pers_cp"></btnbutton

<!-- What it meant, using the Clean Code standards -->
<button class="btn-submit btn-personnel_module btn-copy_action"></button> 

This button got copied/pasted across all the modules and to actions that were not copy. When writing css, people did not know what the classes meant, so they used those classes for sizing, instead of just colors. It was hell to detangle it.

This also applies to for loops. What is better...? (again, actually pulled from our codebase)

for (let k=0; k < vehsAr.length; k++) {
  let vehs = vehsAr[k];
}
/*---- OR -----*/
for (let vehicleIndex=0; vehicleIndex < vehiclesArray.length; vehicleIndex++) {
  let vehicle = vehiclesArray[vehicleIndex];
}

With the for(i) loop, if I decided to change the nesting level, I would end up reusing i and then having to shift everything inside to k. If I instead actually used descriptive variables, there is less work to do. A little effort goes a long ways.

for (let r = 0; r < width; r++) {
  for (let c = 0; c < height; c++) {
    grid[r][c].doSomething();
    // I see immediately that rows is the first layer, and columns is the second layer.
    // "row" and "column" is better than "r" and "c", but "r" and "c" still go a long ways.
    invertedGrid[c][r].doSomething(); // If it goes in natural English reading order, I only have to check in one spot that r and c are backwards.
  }
}
// Invert the nesting order
for (let c = 0; c < height; c++) {
  for (let r = 0; r < width; r++) {
    grid[r][c].doSomething();
    invertedGrid[c][r].doSomething();
    // Notice how the inner formulas don't change?
    // If I used 'i' and 'k', convention is that 'i' is top layer, then 'j', then 'k', then 'l' which looks like '1'.  It get messy.
    // If I swapped height/width while using 'i' and 'k', I'd have to put in much more brain power to make sure height matched with the right letter and that letter matched with the right spot.

  }
}

Update Using i j and k in for loops is perfectly acceptable and is the most common way to write a loop. But the Clean Code standard, based on what little I've read of it, does not like it. At all. Just like Prettier 1.0 hated trailing commas and Prettier 2.0 loves trailing commas. It's a standard. It has a reason behind it. It's not the only way. But using longer/more descriptive variable names is the standards directive being examined here.

| improve this answer | |
  • I don't object to vehicleIndex, but i, j, and k are widely accepted (tradition, from limitations in Fortran) - there is often the expectation of the loop variable named that way. There redundancy (3 times) in let vehicle = vehiclesArray[vehicleIndex];. If I index into an array and get a vehicle (let vehicle = ) that should be sufficient. – Peter Mortensen Apr 29 at 22:37
  • 2
    PageReloaders.EditorCommentsVector the information that it is about vector graphics would be lost there. Vector could also be understood in a mathematical sense as an array of numbers or in a C++ sense as an ArrayList. – TomatenSalat Apr 30 at 6:30
  • @PeterMortensen It was the mathematical tradition of using i,j,k and sometimes l,m,n as throwaway indices (e.g. in Einstein notation) that is why Fortran is like that. Fortran merely popularized it. – richardb Apr 30 at 6:30
  • I also agree that i as an iteration variable is an accepted pattern in simple loops. I might resort to idx_vehicle only if the logic within the loop is complex or if multiple indexes are in play. – Steve Apr 30 at 14:09
  • i as an index is an acceptable pattern. I 100% agree. However, this question was about a different set of standards that has developed beyond what is merely "widely acceptable". Rather, this question is "what does this specific standard actually mean when it says this" – RoboticRenaissance May 1 at 22:32
6

What I would take away from this is when you have items like:

PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorComments
PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorDescriptions

then what you're lacking is context, that you have too many top-level items that deserve to be grouped together in a logical way, and that that grouping provides context. While this is an extreme example, perhaps it could be refactored as:

Comments.Editor.Page.Reloader
Descriptions.Editor.Page.Reloader

(or maybe Page.Comments.Editor.Reloader, whatever!) where the information about whether the page displays vector graphics or not is part of the type of the page, or even the reloader.

Variable names don't exist in isolation, they sit within the context of other objects, and have types, all of these contribute to understanding.

If you have a name that is getting too long, consider whether the variable itself is carrying too much burden.

| improve this answer | |
  • 1
    In a big project, I would have 20 Reloaders in a scope. Everytime I used one I would need to specify the correct namespace of the reloader. A lot of information was lost by your refactoring. Where should you put this now missing information then? Inside a comment? – TomatenSalat Apr 30 at 8:46
  • 3
    I came to say something similar. Whenever a word is redundant within the current context it does not belong in a name. A frighteningly common example of this is putting the name of a system in names inside the system, where they are almost always redundant. – l0b0 Apr 30 at 10:22
  • 3
    @TomatenSalat - well, that's a badly organized project. The principles of abstraction and information hiding don't just serve to insulate classes from each other, they help you work with your code without going into the specific details of everything. The information is not lost, it's just scoped and contextualized - you don't need or want to have all the information thrown in the same place. Instead, you'd have something like code that works with reloaders without knowing what specific reloaders they are. Then the names just need to express concepts relevant to that context/responsibility – Filip Milovanović Apr 30 at 19:02
3

Don't forget that part of the audience of that book are older programmers who cut their teeth on old compilers that had very short name length limits. The first C language standard only required compilers to treat the first six characters of externally-visible identifiers as significant (C89 spec section 3.1.2). The functions and types in the C standard library have extremely terse names, sometimes to the point where they can confuse the unfamiliar.

I've always interpreted Martin's advice as more of a condemnation of the old habits that treat horizontal screen space as something that should be taken into consideration. Modern compilers don't really care about name lengths, and programmers (for the most part) aren't writing code on a console that's limited to 80 columns. The advantages of plainly readable names far outweighs any benefits that you get from short (or overly-long) names.

For example, the C standard library has a function called mbstowcs(). Can you tell what that function does? Me neither. Martin is saying that compressed names like that don't hold much value. If instead the function was named ConvertMultibyteStringToWchar(), you could probably make sense out of code that uses it without having to dig through documentation.

This is certainly not a replacement for comments. Comments record all sorts of additional information, like whether the caller has to free the memory returned by the function, what exceptions the function can throw, whether the function is thread-safe, etc. Comments also record things like why the function is implemented the way that it is. This is all information that you can't reasonably stuff into a name, regardless of how long you make it.

I think the only case where longer names can replace comments is in cases like this:

// tokenize a string
char *strtok(char *s1, const char *s2)
{
    ...
}

But if that's all the information that you're documenting about a function, names aren't your #1 problem.

| improve this answer | |
  • A quality compiler will support external symbols of whatever length the linker supports. If a linker happens to use six-character symbols, any compiler targeting that linker will either have to limit programs to six characters or provide a means for programmers to specify a linker name separate from the C identifier name. Personally, I would have liked to see the Standard recommend a syntax for the latter to facilitate interop with languages whose rules for identifiers differ from those in C [e.g. that may require identifier that contain dollar signs or other such characters]. – supercat May 1 at 21:20
  • @supercat I wasn't talking about quality compilers, I was talking about compilers from before C was standardized. But yes, I definitely agree that the desire for compatibility with those early compilers left some junk in the standard that could have been done much better. – bta May 3 at 18:40
  • If the Standard had recognized the concepts of C implementations that run code directly, produce linkable object code, or produce executable code for use by some execution engine, then it could have allowed for the possibility that language constructs may be limited by the target linker or execution environment. As an example, on Classic Macintosh, many applications could support plug-ins written in C or Pascal, but such plug-ins were not allowed to use any objects of static duration. If the C Standard recognized the concept of execution environments, it could say that a conforming... – supercat May 3 at 18:46
  • ...implementation for an environment that supports static objects should let programmers declare them, but an implementation may target a platform which can't support them if it rejects code containing such declarations. If some particular linker only supports five-character symbols, a C implementation that supports that linker but limits export symbols to five characters may be more useful than one that allows six-character symbols but can't support that linker. – supercat May 3 at 18:48
2

Commenting is inherently dangerous.

  • Use it sparingly for // fixmes

Why dangerous?

  • Code comes and go, but comments are always left behind.
  • People fear deleting comments, because they assume it to be vital true information.
  • Try understanding code with vital FALSE information.

I consider bad commenting, one of the deepest layers in Programming hell.

A function name [for example] however, is less likely to become inaccurate as you change things within it, and if its functionality does change, you are naturally more likely to change the name of it as well.

This is one fundamental but important reason why a long name is preferable over commenting, and why it will lead to cleaner code.

| improve this answer | |
  • I'm not convinced by the assertion that function names are more likely to keep track of reality than comments. I've seen plenty of functions whose behaviour is completely at odds with their name, because developers were too afraid of the impact of renaming. In some cases, you can't rename a function, because it's part of a stable library contract, whereas I've yet to see a case where you can't edit a comment once you realise it's wrong. – IMSoP May 15 at 9:36
  • 1
    @IMSoP, I think to be fair to him, his emphasis is that comments will either be overlooked for maintenance, or that subsequent maintenance developers are often unsure how to evaluate their accuracy or truthfulness. Since the placement and conceptual content of comments often does not conform to any structure, and are not subject to tests, the reliability of comments may be highly questionable. – Steve May 15 at 10:44
  • @Steve Everything you just said applies to function names too; they don't mean anything to the compiler or the testing framework, it needs a developer to think about what they mean in human language and decide if they're still correct or not. – IMSoP May 15 at 11:30
  • @IMSoP, potentially so. It's a difficult issue because I don't agree with him that names should basically be turned into comments (so I don't agree with his proposed solution), but I do agree that comments are prone to be crufty (his description of the problem). If names are more likely to track reality, then in my view this is because they are short, and usually subject to considered design and review, whereas comments are often vague and unstructured expressions of individual developers' thoughts. – Steve May 15 at 12:49
  • 1
    @Steve Yes, I think that's a reasonable way of putting it. As I commented under another answer, it's no good just converting your comment into a name and saying you're done, you've got to address why the code is so complex that you need a long name or comment in the first place. – IMSoP May 15 at 13:16
0

I would like to ignore commenting classes and data structures, because I think that's fine and usually we are more concerned about comments in actual code.

One of the things Uncle Bob does is make his comments a horribly offensive bright red. Not the nice pleasant colors they usually are. This is because he feels that if you have to have a comment in the code it better be worth the horrendous color. If it's worth the offensiveness he leaves it if it isn't he deletes it.

So Uncle Bob does believe that comments should be avoided, but in my mind this is in conflict with another one of this clean coding rules. The rule that the length of a variable name should be proportional to it's scope. So global variables should have long names and local variables should have small names.

For example In one of my functions there was a variable name ip with a comment which shoved in to variable name and I got hostname_or_dotted_decimal_ip. So this eliminated a comment, but then it made the variable unnecessarily long.

I've asked Uncle Bob previously specifically about long variable names in local scopes and his comment was as follows "long variables names in small scopes is obnoxious." I personally think having a somewhat lengthy variable name to kill off a comment is an ok sacrifice given it doesn't make the code obnoxious. If that variable was used 10 times it would probably be obnoxious.

One thing that should be avoided at all cost is hiding the meaningful parts of things at the end of the line. I'm a C developer with zero namespacing and I've never had any function, data structure or variable that long.

PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorComments PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorDescriptions

But if by some force of nature I had to have an abomination like those two things in my code. I would move the difference to the front.

CommentsOfPageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditor DescriptionsOfPageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditor

This principle is covered by Kelvin Henney in Seven Ineffective Coding Habits of Many Programmers Of course if you are in a language that has namespaces you should be using them to avoid insanity such as this.

| improve this answer | |
  • 1
    Is this answer meant to be sarcastic? – Peter Mortensen Apr 29 at 22:28
  • 2
    I was wondering that too. "I set up my IDE to play an air-horn noise whenever I type 'class', and now I agree that Java is too verbose" – Errorsatz Apr 29 at 22:30
  • 2
    I've edited my answer. I'm not entirely sure what was originally sarcastic about it. Some feedback as to why you thought that would be nice. Hopefully this answer does not come off as sarcastic. I'm a fan of Dan Saks who says if you are arguing you're losing. – f3xy Apr 30 at 2:04
  • 1
    Um, I think you're missing a concept here. You've got a variable that stores "either a dotted IP address or a hostname". And your objection is that you can't refer to that easily by a single variable name. Variables are supposed to hold one thing. What is that one thing? Is it "ServerToConnectTo", "ClientAddress", etc? Because if it's "hostname or a dotted IP address", you're either using one variable for two things or you're thinking of your variable the wrong way. – Kevin May 1 at 14:49
  • 1
    I agree with Kevin, all you've done is encoded the comment as a variable name, rather than actually trying to eliminate the need for it. Choosing a more meaningful name isn't a separate concern to put off until later, it's the whole aim of the exercise. Indeed, eliminating the comment might need more than a variable name - should the variable be a stricter type, or more clearly validating against its expected format before use? What previous changes led a variable called ip to not always be an IP address, and have those changes actually been followed through properly? – IMSoP May 1 at 21:55
-1

Make everything as simple as possible, but not simpler.

For a specific class in a big project, long names like these are perfectly fine as long as there is no easier way to express it:

PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorComments
PageReloaderForPagesDisplayingVectorGraphicsThatAreUsedInTheEditorDescriptions

Just keep it stupid simple. Keep the name so obvious that everybody understands it.

Do not scarify descriptiveness for a short name!

If there was a maximum length for variable names, the compiler or IDE would not allow these. Nowadays most developers have 16:9 to 32:9 screens and modern computers have enough memory, so it is possible to choose class names that are much longer and more descriptive than the typical int i, VctGfx gf or VctrGfx vgf abbreviations. Short names like that stem from the old days or from physicists, mathematicians or Fortran developers, but this coding style has many disadvantages in the modern programming world. Object oriented programming is more like using a language than using maths. (Learning computer programming uses similar brain activations to learning a foreign language.) So what applies to language should also apply to programming: neologisms need to be defined when used.

When new developers come into a team, it is much easier for them to understand what a class does, when they do not have to debug through the code to learn that Vector is defined as VectorGraphics in that scope. Also if you have to edit the code after a year, you will find it much easier to understand, when you haven't invented new scope specific vocabulary whose definition is more implied than declared.

If the class has a very specific task, you force each developer to read it, which is annoying at first, but it pays out in the long run.

| improve this answer | |
  • 8
    "Modern computers ... can handle a long name" - the problem is that programmers cannot work efficiently with names of 70 characters or more, and 20 or so syllables. They defy fast pronunciation (so they are inefficient for talking), and they defy visual shape recognition (so they are inefficient for reading). Remember the challenge here is to name things - even 'War and Peace' had a snappy name! – Steve Apr 30 at 10:09
  • @Steve "talking about code". The most efficient way to talk about code is with the viewer sitting next to you or by sharing your screen. Talking about what the code looks like in your head is just a "map" of the reality and you could come to conclusions that are not possible or too complicated to implement. Talking about architecture is something different. – TomatenSalat Apr 30 at 11:34
  • 3
    "When you know what the class does you do not even have to read its whole name anymore." - I'm afraid I'm inclined to disagree. Not only do names obviously have to be re-read, but they also form part of the visual clutter that has to be navigated overall. I think even you'd accept that a 1,000 character name was too long - that at some point, length manifests itself as a problem. Offhand, I'd say that the limit is around 20 chars. Perhaps 30 or 40 chars max if a justifiable system of prefixes and underscores to separate words is employed. Never 70. – Steve Apr 30 at 12:53
  • 2
    the limit does not need to be arbitrary in the sense of being a diktat that a programmer can never override for good reason. But if the length of the names arises from the inherent complexity, I'd be questioning whether that complexity can't be managed in any other way, or whether the project itself is too complex to be commercially sensible. Unit tests are a different beast I will agree. – Steve Apr 30 at 13:59
  • 2
    @TomatenSalat "When the Project has a complexity that requires a long name, then even a ridiculously long name is fine". If you have a variable / function / class for which the purpose is so complex that you need an excessively long name, then it's probably a candidate for refactoring. Personally I find the two examples you've given in this answer to be utterly unreadable. I'd have to pause and read and re-read it a couple of times to figure out what is going on. – Jon Bentley May 1 at 9:38

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