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().
Related
I have several patterns for finding information about people including things like:
What is {personName} phone number
and
Tell me about {personName} in {Department}
(Department being a custom entity)
However, no matter what kind of training I give it, including specific mentions of things like "April in Marketing", it always comes back with "April" being a datetimeV2 entity.
Is there a way I can force it to recognize that, within the name patterns, the string "April" is always a name, not "XXXX-04" datetimeV2 entity?
(We have no other people here with names the same as months, but I have to assume if we did, we'd need a workaround for those as well.)
As a quick fix for now, Instead of a Simple Entity called personName in the Patterns, create a Pattern. Any entity (Go to Entities Create, will be one of the options), and put that entity whatever you call it (personNameAny) and put it in the pattern, and it will achieve the scenario you want where personNameAny acts as a placeholder for whatever text that happens after words like “what is” put in the utterance. This comes with drawbacks and isn’t the optimum solution but it can cover a lot of scenarios.
https://learn.microsoft.com/en-us/azure/cognitive-services/luis/luis-how-to-add-entities
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.
The VERSIONINFO resource has an InternalName property. Why is this needed and what is its meaning? Is it a required property for every dll? How is this property used?
Fairly subjective, but VERSIONINFO certainly looks like it was designed by a committee instead of a programmer. They didn't know when to stop adding features and everybody got something in that they thought was important. The exact reasoning is lost in the fog of time and MSDN isn't specific enough to guess at the intention.
At least part of the schizophrenia is that the resource is intended both to be read by a human, it fills the Details property sheet that you see in Explorer, as well as machine readable through GetFileVersionInfo() and friends. A particularly painful winapi to use. This does for example somewhat explain the oddity of having two ways to specify the file and product version numbers. Both as a binary number and as a string. With the intention that the string can be localized, perhaps.
InternalName fits the machine-readable usage, note how it does not show up in the Details property sheet. Which makes it "internal", perhaps. And note that the OriginalFilename property does show up, thus intended for a human.
There is very little guidance on why it matters since there is no fixed usage of the property. It doesn't show up on the property sheet and afaik it doesn't get used by Windows itself at all. It is therefore completely up to you want you enter here, do note that it is required property. Maybe you'll have a use for it some day, I personally never found one. Just enter the name of the module as you originally specified it in your spec, simply set OriginalFilename to the same string with, say, .dll appended.
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?
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.