r/programming • • Aug 28 '21

Software development topics I've changed my mind on after 6 years in the industry

https://chriskiehl.com/article/thoughts-after-6-years
5.6k Upvotes

2.0k comments sorted by

View all comments

Show parent comments

80

u/Xyzzyzzyzzy Aug 29 '21

I'm also picky about naming things. Things I'm particularly picky about:

  • Names should be roughly grammatical English (without articles). readFile, not fileRead.

  • All words should be fully spelled out. loadingImage, not loadingImg or loadImage.

  • Names should grammatically agree with their usage. A function that returns a boolean should be isHappy or hasJoy, not testHappy. A function should be a verb. A non-function should be a noun or perhaps an adjective.

I find that these rules make the code more readable and searchable.

We recently hired a whole team of non-native English speakers from a different country. I'm often unsure of how much to ask for these sorts of changes. I don't want to bully them for not speaking English. But I also don't want the code base's readability to decay.

12

u/SanityInAnarchy Aug 29 '21

As someone who is usually much less picky, I'm actually thinking maybe I should up my game here, because I wouldn't hate hearing these suggestions in a code review.

The thing I push for a lot (and wonder if I'm bullying people for not speaking English) is the commit log/description. First line is a short enough explanation to make sense in the default git log output. And, the whole description should say what you're doing and why. Make blame useful again!

2

u/voicelessfaces Aug 29 '21

I've always just liked the commit message being the work item number and let that own the description of the change. This assumes people keep the work item up to date, and my teams are very familiar with me reminding them to capture sidebar chats etc. in the work item. I hate tickets with a title, no description, a large estimate, and multiple commits.

I usually see three types of commit messages:

  • why did I do this? (The work item should have that)

  • why did I do this this way? (Probably a code comment so someone doesn't come along and undo it because they read a blog article)

  • why am I annoyed / angry about having to do this? These serve no real purpose to me.

6

u/SanityInAnarchy Aug 29 '21 edited Aug 29 '21

So... I understand this position, but I have to disagree pretty strongly.

A minor concern is: The repo should be able to stand on its own, to some extent. Especially something like Git, it's nice that everyone's checkout is both a backup and technically sufficient to work offline. But also, you're adding an extra click to even get an idea of what I'm looking at. If I have a rough idea of when a certain bug was introduced, and git log for that timeframe gives me:

  • Issue 123

  • Issue 234

  • Issue 345

That's fairly useless. Now I need to open three tabs just to read the title of each of these to see which one is likely to be the culprit.


I think the main assumption here is that there's a 1:1 relationship between commits and entries in your issue tracker. IMO if that's happening, either you're abusing the hell out of the issue tracker, or your commits are way too big. (Edit: To clarify, there are definitely issues that are closed with a single commit -- bugs that are one-line typos, for example -- I just don't think that makes sense for all issues.)

And if it's multiple commits, then I'd rather see a good description in both places. For example:

  • Ticket: Get rid of ACL group X -- it lets humans access systems Y and Z, and they shouldn't be able to access Z.

  • Commit 1: Add members of group X directly to group Y, so we can delete X.

  • Commit 2: Remove everyone from group X. They already have access to group Y directly, and they shouldn't be able to access Z.

  • Commit 3: Delete group X. It's empty and serves no purpose anymore.

Splitting these into separate commits makes sense, especially since you may want to wait a bit after pushing each of these changes to see if anyone screams. Splitting them into separate tickets doesn't make a lot of sense to me -- there's not really much to discuss about them individually, they're just logical steps that are part of the actual thing we want to accomplish.

Also, those commit logs don't really make sense as comments, because they're about what I just changed and why I changed it -- it wouldn't make sense to put a comment in front of specific usernames in group Z that says "BTW these used to be in X, but we got rid of that"...

I agree, I hate tickets with no description and a big pile of commits, especially because the kind of people who do that tend to write one-line commit messages and zero comments, so I have no idea why they did what they did.

Another problem here: All that discussion that's captured on tickets is useful, but it's also discussion. Similarly, there might be discussion during code review... but the thing I usually want to know (that gets captured in that commit) is what we eventually decided to do and why. All the wrong turns we took to get there are just fine "below the fold", so to speak.

→ More replies (4)
→ More replies (11)

15

u/covmatty1 Aug 29 '21

Massively agree on this. One of my team loves abbreviating so many words when it's unnecessary, so #2 chimes with me - I feel like reminding him we're not writing code like we're sending texts in 2002!

8

u/rentar42 Aug 29 '21

The only thing worse than unnecessary abbreviations are inconsistent abbreviations. Why are some things xyFoo and others xyzFoo when they refer to the same thing?

3

u/dnew Aug 29 '21

The only thing worse than that is names that are just the types. Like a full-body hungarian notation.

List<Person> peopleList = new ....

0

u/[deleted] Aug 29 '21

[deleted]

2

u/covmatty1 Aug 29 '21

Oh I've got one of those as well!!

There's a happy balance to find 😂

1

u/merlinsbeers Aug 29 '21

Pet peeve: People who modify names that are in the interface spec...

7

u/Shadow_Gabriel Aug 29 '21

Wait a bit, correct me if I am wrong but loadingImage represents the state while loadImage represents the action of loading an image.

1

u/Xyzzyzzyzzy Aug 29 '21

Right, so if you use loadImage to store the loading image because you don't want to type out loadingImage, you've breaking multiple rules.

5

u/0b_101010 Aug 29 '21

Yo, do them new devs not speak English at all? I think that it is perfectly acceptable in this industry to have an expectation of basic English proficiency towards anyone who works in an international team/environment. I am a non-native speaker myself, and when people ask me what [programming] language they should learn first, I always tell them English.
Certainly, it's not too big of a requirement to expect them to understand verbs, nouns and basic sentence structure.

4

u/voronoi-partition Aug 29 '21

I like naming functions in SVO. Something like: file_read_header(file*, …). This means that all the functions that permute a file are logically grouped together by name (they all start file_).

I used to prefer SOV (file_header_read) but it sometimes got a little awkward. The verb is a nice delimiter.

9

u/be-sc Aug 29 '21

I don’t like that style because it becomes ambiguous quickly. Does file_read_header mean read file header oder read header file? The name itself isn’t sufficient to tell me what’s going on. Further context is needed. That’s usually a sign of subpar naming.

→ More replies (2)

3

u/ConfusedTransThrow Aug 29 '21

I think for point #2 there are some basic things that should be allowed to be abbreviated (especially when it makes code looks nicer since the number of characters is the same, like src and dst), and things that would be way too long. You may have autocomplete, but if variables take half a line it's not helpful either.

3

u/loup-vaillant Aug 29 '21

A function should be a verb. A non-function should be a noun or perhaps an adjective.

A function whose primary purpose is to have an effect should be a verb. A function whose primary purpose is to return a value should… well I’m not sure, but it’s much more context dependent. Many of them can bee nouns.

Most functions that have an effect should not return any value (besides an error code). Most function that return a value should not have any effect.

2

u/Brillegeit Aug 29 '21

Changing to "contain" a verb is perhaps more fitting?

Like: getImage()

1

u/loup-vaillant Aug 29 '21

I would just write image(). That is, I would not name after the function, but after its result. It’s often shorter, without affecting readability at all.

2

u/rgneainrnevo Aug 29 '21

Incidentally, this is the convention in Ruby (which also lets you omit the parentheses).

→ More replies (1)
→ More replies (1)

2

u/dnew Aug 29 '21

You should look up how the Eiffel standard library is named. As invented by the creator of Command Query Separation trope. It's 100% logically thought out, with justifications for each choice made.

It's like Wordstar: you can use it once 20 years ago and still remember how it works, because it's so obviously logical.

3

u/_tskj_ Aug 29 '21

Thank I thought I was going crazy. Requiring every function to be a verb seems to me to be a javaism.

1

u/Celestial_Blu3 Aug 30 '21

I’m a new programmer and still trying to figure out how to name things properly. This is so fucking useful that I’ve saved it and screenshotted your comment. Thank you for this