The QA manager where I work just informed me there is a bug in my desktop app due to the sign-on prompt being "Operator Id" when it should be "Operator ID". Her argument being that "Id" refers to the ego portion of Freud's "psychic apparatus" and is not semantically correct.
Now being an anal engineer (AE) I of course had to go and lookup Id vs ID and from my cursory investigations (google) it seems ID is just as commonly used for Freud's ego as Id is.
So my reasoning would be that Id is a shortened version of "Identifier" and is more correct or at least more commonly used than ID which would typically indicate a two word abbreviation.
I could just change the UI but then I wouldn't be holding up my profession as an AE so I was wondering if there any best practices or references for this sort of thing that I could use to support my argument? Keeping in mind that this question relates to the user interface and not the source code where abbreviations and casing are a whole different branch of philosophy.
According to Merriam-Webster, the abbreviation is "ID". If it were a correct abbreviation, it would have to be "Id." with the period.
Personally, I use "Id". The compiler doesn't care but my eyes do. Compare:
GetIDByWhatever <-- looks terrible
GetIdByWhatever <-- oh so pretty!
Aesthetics is more important than grammar when it comes to code, always. (Update: 4 years later, I don't stand by this statement anymore)
The 'D' doesn't stand for anything, so I've always considered it an abbreviation, not an acronym - and therefore I too use 'Id', not 'ID'.
I don't know about your qa's reasoning - words can have more than one meaning - this is not unusual in English :)
But it looks like the common usage is actually 'ID' (right or wrong :P), which is probably the format your users would expect.
As an UAUA (ultra-anal usability analyst), please use ID instead of Id.
Visually, it's more recognizable in English. Grammatically, "Id" is a word (rhymes with "squid") and the Freudian definition has been given above. We're never verbally asked to show "id", but "ID." I.D. is fine but passe, as the periods imply multiple words.
So.
Just use ID, okay?
OK.
It's interesting that so many feel "Id" should be the way to go.
I feel "ID" is appropriate because it hints at how we pronounce it -- I.D. Also, when I read "Id" in a running sentence, I sometimes have to come back and read it again just to ensure it's not a typo for "is" or "it".
So, as a technical writer, this is an issue that comes up for me quite regularly when reviewing other people's work, whether it be programmers, BAs or other writers. Typically, id refers to ego as others have said before me and the accepted abbreviation for identification is ID, just because plenty of people don't know or understand the rule doesn't mean that they are correct (sorry to be blunt), mind you the rules for punctuation and spelling to a large degree are almost as changeable as fashion!
However, what no-one seems to have asked is, does your company have a standard? At the end of the day if your company has a style guide and they have covered this topic in that guide, you should follow the guide. If it is not covered, then may I suggest that you raise the issue with the person that maintains the guide and include any stakeholders in the conversation. Consistency is key here. If the company you work for doesn't have a style guide, then perhaps it is time to start one!
Hope this helps...
The QA manager's line of reasoning is silly. Lots of English words have multiple meanings. "Lead", "lead", "lead" (metal, be at the front of, or a connector).
I would just try to be consistent with the capitalization used elsewhere in the app.
User interface and code are very different beasts...
"ID" is the correct answer for a user interface.
In code, consistency is your friend. Whether you like it or not, go with what is already there elsewhere in the code. If it's not there, then read up and make a decision, or get with the team and work out a way to go that everyone can agree to. Consistency makes life so much easier.
I prefer Id because when used with other 2-letter text, it doesn't become a single all-caps word
Photovoltaics systems ... PVID (one word or 2?) PvId (much more clear).
ID = Idaho! Id = Freud! Let the OCD begin!
There is a little OcD in all of us!
Anyway, the google style guide says this:
"ID: Not Id or id, except in string literals or enums. In some contexts, best to spell out as identifier or identification."
I'm going with that.
Microsoft is more vague, from what I could find.
as a short version of Identifier, I would use Id. Also ID it's freaky when you have functions like
getUserIDByName()
Multiple capitals in domain terms are quite problematic with CamelCase, as they can produce ambiguities and therefore dishomogeneity in your interfaces and namings
How would you say it if you were reading out loud? I'd pronounce the two letters. ID is correct, analogous with similar abbreviations such as TV. (No dots, please, as the letters don't stand for anything.)
When I'm dealing with abbreviations like this, I like to format them in small block capitals, but that's just a personal taste. Capitals, anyway.
(But I probably would continue to use Id in the code itself.)
I think its depend on the way we spell. We don't spell "it", but "ai-di". Id-ID is spell by two sounds, so people make the D in cap to avoid thinking id is a "word". Its more like a character symbol. I like the "ID" more, just because it's nicer.
ID is correct. I have been in the Id camp for years, simply because I believed it was an argument between abbreviations and acronyms. Until one day I learned of a 3rd type (subtype really) called Initialisms which are specific to abbreviations or acronyms that are specifically read one letter at a time rather than pronounced as a single word. Initialisms are all caps.
Related
I'm currently working on an internationalisation project for a large web application - initially we're just implementing French but more languages will follow in time. One of the issues we've come across is how to display adjectives.
Let's take "Active" as an example. When we received translations back from the company we're using, they returned "Actif(ve)", as English "Active" translates to masculine "Actif" or feminine "Active". We're unsure of how to display this, and wondered if there are any well established conventions in the web development world.
As far as I see it there are three possible scenarios:
We know at development time which noun a given adjective is referring to. In this case we can determine and use the correct gender.
We're referring to a user, either directly ("you") or in the third person. Short of making every user have a gender, I don't see a better approach than displaying both, i.e. "Actif(ve)"
We are displaying the adjective in isolation, not knowing which noun it's referring to. For example in a table of data, some rows might be dealing with a masculine entity, some feminine.
Scenarios 2 and 3 seem to be the toughest ones. Does anyone have any experience handling these issues? Any tips would be appreciated!
This is complex, because we cannot imagine all the cases, and there is risk to go in "opinion based" answer, so I keep it short and generic.
Usually I prefer to give context in translation (for translator), e.g. providing template: _("active {user_name}" (so also the ordering will be correct if languages want different ordering).
Then you may need to change code and template into _("active {first_name_feminine}") and _("active {first_name_masculine}") (and possibly more for duals, trials, plurals, collectives, honorific, etc.). Note: check that the translator will not mangle the {} and the string inside. Usually you need specific export/import scripts. Or I add a note inside the string, and I quickly translate into English removing the note to the translator). Also this can be automated (be creative on using special Unicode characters which should not be used in normal text, to delimit such text).
But if you cannot know the gender, the Actif(ve) may be the polite version used in such language. You need a native speaker test, and changes back and forth.
I am writing an app that has a sign-up form. This article made me doubt everything I knew about human names. My question is: does a person's name necessarily have positive length? Or can I validate names in this way and be confident that I have not denied anyone their identity?
P.S.: one might ask why am I validating at all. The answer is that this is for a school project and proper validation is a part of the mark. The article above proves that person's name can be pretty much any string of positive length but I don't know if zero length is OK.
With all types of programming, you have to draw a distinction between what is meaningful in the real world, and what is meaningful for your software solution.
How the data is to be used will validate what type of validation is required.
For instance, if your software interfaces with a government API, and the government API requires a first name and surname, you should do the same.
If you're interacting with bank accounts, you may have a single string which represents that account name, which many or may not be a human name or not, but may have other constraints around length.
If the name is only to be used for display purposes, maybe there is no point to capture the name at all, and instead you should capture a preferred display name (which doesn't needlessly assume a certain number of name components).
When writing software, you should target to make as few assumptions as possible, unless those assumptions will cause an increase in complexity of your software solution. If the software requires people to have non-empty names, then you should validate at the border that this is true.
In addition, if you were my student, you would have already lost marks for conflating null, and an empty string. In this instance, null would represent you lack data about the name, and an empty string would indicate that user has specified that their name is empty.
Also, if you decide not to validate something, you should at least leave a comment to indicate that you thought of it. If you do something unusual, it's possible a future developer may come along and fix the "bug". In addition, this helps you avoid losing marks.
I named one of my boolean parameters didInfoChange.
Many people on my team tell me to change it to isInfoChanged, which I don't agree. It maybe because my team members aren't native English speaker (neither am I), but I feel that ifInfoChanged is just isn't right.
didInfoChange -> Did information change? -> True/False
is pretty understand in my oppinion
isInfoChanged -> is info changed?
just does not sound right.
It's probably not a big deal to fight about this, but I did some search and people do not really use did for flag name. I'm ok with hasInfoChanged but has and did is basically the same thing.
I'm wondering why is did not ok?
There are two questions here:
1) Which is better, didInfoChange or isInfoChanged?
The English word "change" can be transitive or intransitive, but in this context it is clear that "the info is changed" and "the info did change" mean exactly the same thing. (There is a subtle difference in connotation, but it is of no importance here.) The two names have the same length. There seems to be no difference except style convention.
2) If your way is better than theirs, what should you do?
Consider the consequences of your actions.
If you have the power to persuade the rest of the team to use your variable name, at no cost, then do so. If doing so would cause stress (e.g. by commanding your subordinates to do something they consider a bad idea), then the improvement in style probably isn't the cost to the group dynamic.
If you cannot persuade them, but you can prolong the argument and prevent the team from doing constructive work, then... don't. Use their variable name.
If you cannot prolong the argument, but you can make yourself unpopular by being argumentative, then... don't. Use their variable name.
Beside is it is also sometimes admissible to use has in naming Boolean getter-methods, depending on which auxiliary verb would be used in spoken language; I never saw did as part of a Boolean identifier.
With hasInfoChanged you would keep the participle ending (e)d. Maybe that satisfies the rest of your team.
infoChanged could be mistaken for an EventHandler-Delegate.
Unfortunately I am not a native English speaker, either.
It depends on the context and what this field "really" expresses in semantics.
didInfoChange puts emphasis on the completed action (past-tense implied) by "did" + action-verb
isInfoChanged puts emphasis and indicates the current-state when asking now by is + state; where the past-tense is indicated by the passive "changed"
Note: Info is the vague part in the name. is is a common indicator for boolean fields or getters - indicating a question (same like has or can). did is rather rarely used because we usually ask for the current state at runtime using is. The completion or history can be expressed by other parts of the name, like specific action-verb in past-tense.
Other ways of recording/asking for change
What about asking more about the context of this change:
Who did change the information ? Like an audit field (changedBy) conveying also who did change something.
When was the information changed ? Like a audit date/time field (changedAt), not only telling that it was changed, but also when.
What information was changed ? Like capturing the change itself (lastChange) which could also be null if not changed at all.
In most ORM-frameworks which capture audit-information like this (when/who/what was changed) we can see fields like createdBy or createdAt for the initial user and timestamp when created, modifiedBy or modifiedAt for the user and timestamp that last updated or changed the object.
Sometimes also a version-indicator helps to keep track of the number of changes.
Keep it simple
One compromise could be inspired by KISS-principle:
Have a boolean field changed which could for enrichment-purpose also hold a timestamp along with a getter named isChanged to query the current state like asking a human question like:
is [this] changed ?
Note: [this] is implied when invoking the method on the object like this.isChanged().
In the latest code review I was asked, why did I change the method name from GetHDRFrame to GetHdrFrame, while HDR is an abbreviation. I'm pretty sure there was such recommendation in Code Complete: when using abbreviations in CamelCase names, treat them as regular words. But I cannot find the place where it is written. Could somebody give me an exact phrase in Code Complete, where it is stated?
There is a similar question with the useful links to MS rules, but I'm looking for Code Complete quote.
As far as I've been able to determine, there is no such advice in Code Complete. But it does say:
People have managed to have zealous, blistering debates over fine
points such as whether the first character in a name should be
capitalized (TotalPoints vs. totalPoints), but as long as you and
your team are consistent, it won't make much difference.
And that may help you avoid such nitpicking in future code reviews. ;-)
This may be a stupid question, but here goes.
I've seen several projects using some translation library (e.g. gettext) working with plain english placeholders. So for example:
_("Please enter your name");
instead of abstract placeholders (which has always been my instinctive preference)
_("error_please_enter_name");
I have seen various recommendations on SO to work with the former method, but I don't understand why. What I don't get is what do you do if you need to change the english wording? Because if the actual text is used as the key for all existing translations, you would have to edit all the translations, too, and change each key. Or don't you?
Isn't that awfully cumbersome? Why is this the industry standard?
It's definitely not proper normalization to do it this way. Are there massive advantages to this method that I'm not seeing?
Yes, you have to alter the existing translation files, and that is a good thing.
If you change the English wording, the translations probably need to change, too. Even if they don't, you need someone who speaks the other language to check.
You prep a new version, and part of the QA process is checking the translations. If the English wording changed and nobody checked the translation, it'll stick out like a sore thumb and it'll get fixed.
The main language is already existent: you don't need to translate it.
Translators have better context with a real sentence than vague placeholders.
The placeholders are just the keys, it's still possible to change the original language by creating a translation for it. Because when the translation doesn't exists, it uses the placeholder as the translated text.
We've been using abstract placeholders for a while and it was pretty annoying having to write everything twice when creating a new function. When English is the placeholder, you just write the code in English, you have meaningful output from the start and don't have to think about naming placeholders.
So my reason would be less work for the developers.
I like your second approach. When translating texts you always have the problem of homonyms. Like 'open' can mean a state of a window but also the verb to perform the action. In other languages these homonyms may not exist. That's why you should be able to add meaning to your placeholders. Best approach is to put this meaning in your text library. If this is not possible on the platform the framework you use, it might be a good idea to define a 'development language'. This language will add meaning to the text entries like: 'action_open' and 'state_open'. you will off course have to put extra effort i translating this language to plain english (or the language you develop for). I have put this philosophy in some large projects and in the long run this saves some time (and headaches).
The best way in my opinion is keeping meaning separate so if you develop your own translation library or the one you use supports it you can do something like this:
_(i18n("Please enter your name", "error_please_enter_name"));
Where:
i18n(text, meaning)
Interesting question. I assume the main reason is that you don't have to care about translation or localization files during development as the main language is in the code itself.
Well it probably is just that it's easier to read, and so easier to translate. I'm of the opinion that your way is best for scalability, but it does just require that extra bit of effort, which some developers might not consider worth it... and for some projects, it probably isn't.
There's a fallback hierarchy, from most specific locale to the unlocalised version in the source code.
So French in France might have the following fallback route:
fr_FR
fr
Unlocalised. Source code.
As a result, having proper English sentences in the source code ensures that if a particular translation is not provided for in step (1) or (2), you will at least get a proper understandable sentence than random programmer garbage like “error_file_not_found”.
Plus, what do you do if it is a format string: “Sorry but the %s does not exist” ? Worse still: “Written %s entries to %s, total size: %d” ?
Quite old question but one additional reason I haven't seen in the answers yet:
You could end up with more placeholders than necessary, thus more work for translators and possible inconsistent translations. However, good editors like Poedit or Gtranslator can probably help with that.
To stick with your example:
The text "Please enter your name" could appear in a different context in a different template (that the developer is most likely not aware of and shouldn't need to be). E.g. it could be used not as an error but as a prompt like a placeholder of an input field.
If you use
_("Please enter your name");
it would be reusable, the developer can be unaware of the already existing key for an error message and would just use the same text intuitively.
However, if you used
_("error_please_enter_name");
in a previous template, developers wouldn't necessarily be aware of it and would make up a second key (most likely according to a predefined wording scheme to not end up in complete chaos), e.g.
_("prompt_please_enter_name");
which then has to be translated again.
So I think that doesn't scale very well. A pre-agreed wording scheme of suffixes/prefixes e.g. for contexts can never be as precise as the text itself I think (either too verbose or too general, beforehand you don't know and afterwards it's difficult to change) and is more work for the developer that's not worth it IMHO.
Does anybody agree/disagree?