Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Taming names in software development

simplethread.com

Post reply on HN
Print view View original

31–40 of 44 posts

Re: Taming names in software development

#31

Post by anon121122 »

furyofantares wrote: post #26
furyofantares wrote: post #24

> I understand exactly what BasicReviewableFlaggedPostSerializer is on my first time seeing it. I don't. I think I figured it out after reading it half a dozen times (except for Basic, no clue there) before working out that Post is probably a noun. So even this requires context to just read and know what it does, my first read of it I only knew what Serializer meant.

Or maybe I'm still not getting it, my read is there are posts, they can be flagged, flagged posts can be reviewed, and this is a "basic" serializer for flagged posts that have yet to be reviewed. But why you'd need such a specialized serializer is beyond me, (let alone presumably less basic one as well) it seems like such drastic overkill that maybe I still don't get what the name means.

> Or maybe I'm still not getting it, my read is there are posts, they can be flagged, flagged posts can be reviewed, and this is a "basic" serializer for flagged posts that have yet to be reviewed.

I think you are right. The name is pretty clear to me, but that may be because I have worked on similar code bases where this naming is used by convention. Reading code requires knowing the domain and I'm not sure if a shorter name is more clear. You need domain knowledge to know what a post is, and what it means that it has been flagged.

You probably made a very accurate guess based on your knowledge of forums and moderator systems. This may not be apparent to all, and shorter names will probably not help much. In addition, if they shortened the name to "Serializer", "PostSerializer" or even "FlaggedPostSerializer" it could conflict with other serializers in the project.

> But why you'd need such a specialized serializer is beyond me,

I totally agree with your point. They may have their reasons, but it seems to me that a "ReviewableFlaggedPost", "FlaggedPost" and "Post" should have very similar needs and could be solved by structuring them differently (perhaps by using composable classes that can each take care of their own serialization)

Regarding the use of "Basic", it also triggers a "code smell" reaction from me. It may make sense to them, and it's hard for me to make any definitive comments without knowing the rationality behind it. My guess is that they have different types of responses based on the same "post" object. "Basic" may include a subset of the "Full" response, such as id and title only.

In those cases I tend to prefer separate DTOs, like "PostSummaryDTO" and "PostDTO" that can be re-used by composability for different responses (flagged for review etc.). This may of course not be the best choice for all usages, so I would need to know more to say something conclusive about this particular case

Re: Taming names in software development

#33

Post by mumblemumble »

durandal1 wrote: post #11
drekipus wrote: post #5

Earlier quoted context omitted.

This came up at my work Christmas party. One colleague on my team (1) hates my reviews because the naming things I point out are way too pedantic. Another colleague (2) in our same team loves my reviews because it makes them think about how it's read and understood. It's difficult to convey why naming is important. (1) also feels that the code needs a lot more comments and berates others for not commenting their code…

One thing that I've found over and over again, is that if something is hard to name, there is often a problem with the abstraction itself. Most common issue is that the thing that resists naming is doing multiple things and that it should be split up in smaller parts that focuses on something small that can be simply named.

I've also discovered that the problem with the abstraction itself that the naming difficulty is pointing out might be the mere fact that this abstraction exists in the first place.

We've got such a fetish for reusability that it often overwhelms any care we might have given to comprehensibility.

Re: Taming names in software development

#34

Post by pydry »

durandal1 wrote: post #11
drekipus wrote: post #5

Earlier quoted context omitted.

This came up at my work Christmas party. One colleague on my team (1) hates my reviews because the naming things I point out are way too pedantic. Another colleague (2) in our same team loves my reviews because it makes them think about how it's read and understood. It's difficult to convey why naming is important. (1) also feels that the code needs a lot more comments and berates others for not commenting their code…

One thing that I've found over and over again, is that if something is hard to name, there is often a problem with the abstraction itself. Most common issue is that the thing that resists naming is doing multiple things and that it should be split up in smaller parts that focuses on something small that can be simply named.

I usually find in every project that there are few terms that are overloaded to mean multiple conflicting things.

On one project it was so bad that every time a particular word was used in conversation I had a mini freak out because it essentially referred to six related but very distinct things. I had to figure out which one people meant, assuming they even knew themselves.

It wasn't like these things were subtypes of that word either. The word had just been bastardized beyond recognition.

I tried to make up six new meaningful names and "ban" anybody from using the original word but it didn't stick particularly well. We never did manage to exorcize the original word from the code base, so it hung around misleading people.

It did lead to bad abstractions but the root of the problem wasn't the abstractions themselves but the fact that this word was used so indiscriminately and inappropriately.

Re: Taming names in software development

#35

Post by mumblemumble »

dmurray wrote: post #15
thaumasiotes wrote: post #8

Earlier quoted context omitted.

> but let’s not stop calling ... the database temmp_v3_old_Udpate_RstdnewV2 I worked briefly on a codebase that was otherwise produced by Chinese programmers (in China). It did feel somewhat surreal seeing variable names that were in English but misspelled, particularly when e.g. several classes all had a field of the same name, except that in one of them, the name was misspelled. I assume it didn't bother them becau…

I've seen the same thing many times with English-speaking programmers. Plenty of people just don't spot that 'udpate_history' is misspelt.

This is me.

The invention of the symbol name spellchecker a decade or so back has been a wonderful boon for me. It's a little annoying to teach it the new jargon when I'm getting started in a new codebase, but it's easily a net time saver. Catching spelling errors when you first create the new symbol is always cheaper than fixing them after it's being referenced from 15 different files and can't be fixed without another code review.

Re: Taming names in software development

#36

Post by pastacacioepepe »

Once you understand the domain you're working on and you've architectured your solution in a way that makes sense, only then naming in your code will get right and without much additional effort. Forget about naming, it is a side effect of your understanding of the issue at hand.

Re: Taming names in software development

#37

Post by dmurray »

maccard wrote: post #29
dmurray wrote: post #15

Earlier quoted context omitted.

I've seen the same thing many times with English-speaking programmers. Plenty of people just don't spot that 'udpate_history' is misspelt.

And sometimes that mistake propagates and leaves us 25 years later still using referer [0] [0] https://annaken.github.io/a-brief-history-of-the-referer-hea...

This one always seemed to me like a plausible alternative spelling (cf. traveler for traveller).

Maybe the reviewers who let this through were speakers of British English who knew it was misspelt but conceded it without a fight, having already lost on color, gray, center...

Re: Taming names in software development

#38

Post by furyofantares »

anon121122 wrote: post #31
furyofantares wrote: post #26

Earlier quoted context omitted.

Or maybe I'm still not getting it, my read is there are posts, they can be flagged, flagged posts can be reviewed, and this is a "basic" serializer for flagged posts that have yet to be reviewed. But why you'd need such a specialized serializer is beyond me, (let alone presumably less basic one as well) it seems like such drastic overkill that maybe I still don't get what the name means.

> Or maybe I'm still not getting it, my read is there are posts, they can be flagged, flagged posts can be reviewed, and this is a "basic" serializer for flagged posts that have yet to be reviewed. I think you are right. The name is pretty clear to me, but that may be because I have worked on similar code bases where this naming is used by convention. Reading code requires knowing the domain and I'm not sure if a sho…

Yep, I searched github for it and it looks like exactly that for Discourse. I don't have an problems with the code now that I've seen it (though still don't know why it's Basic except that it's a subclass of BasicReviewableSerializer, which my question would extend to.)

Re: Taming names in software development

#39

Post by thaumasiotes »

dmurray wrote: post #37
maccard wrote: post #29

Earlier quoted context omitted.

And sometimes that mistake propagates and leaves us 25 years later still using referer [0] [0] https://annaken.github.io/a-brief-history-of-the-referer-hea...

This one always seemed to me like a plausible alternative spelling (cf. traveler for traveller ). Maybe the reviewers who let this through were speakers of British English who knew it was misspelt but conceded it without a fight, having already lost on color , gray , center ...

Traveler is stressed on the first syllable; referrer is not.

Re: Taming names in software development

#40

Post by zeroimpl »

rTX5CMRXIfFG wrote: post #21
wging wrote: post #16

Earlier quoted context omitted.

I disagree. The utility of short names is not just that it takes less effort to write them. They're also far easier to read and understand. IDE autocompletion doesn't help with that, nor does any other tooling, really. Since code is read much more frequently than it's written (including but not limited to any time that related code has to be changed), names should be as short as possible without sacrificing clarity.…

The problem with `timeoutMs` or `timeoutSecs` is that if you have a policy that you shouldn't contract words (possibly founded on a first principle that you value clarity in your coding standards), then you're going to spend time justifying why a pull request gets rejected when someone names a type `SearchCntrlr` or `SubmtBtn`. Before you know it, you'll have spent hours just debating and getting no work done, wherea…

Also is it timeoutMs, timeoutMS, or timeoutMillis?
Post reply on HN