I have a function that decorates a string. If the decorated string is again fed to the function, it is guaranteed not to change. How is the standard naming convention for such a function? I'll probably create a namespace because I need to have a few of those functions.
I've come up with:
repetition_safe.decorate(me);
fixpoint_gen.decorate(me);
one_time_effect.decorate(me);
but I don't really like any of these.
How would you name the namespace or function?
How about:
StringDecorator.MakeImmutable(input);
I think "MakeImmutable" is better than "Decorate" as the later is ambiguous i.e. a user reading the code won't know what "decorate" does, whereas "makeImmutable" will inform the user that this function will make the input string immutable/non-changable.
Related
I implement several global functions in our library that look something like this:
void init_time();
void init_random();
void init_shapes();
I would like to add functions to provide a check whether those have been called:
bool is_time_initialized();
bool is_random_initialized();
bool are_shapes_initialized();
However, as you can see are_shapes_initialized falls out of the row due to the fact that shapes is plural and therefore the function name must start with are and not is. This could be a problem, as the library is rather large and not having a uniform way to group similiar functions under the same naming convention might be confusing / upsetting.
E.g. a user using IntelliSense quickly looking up function names to see if the libary offers a way to check if their initialization call happened:
They won't find are_shapes_initialized() here unless scrolling through hundreds of additional function / class names.
Just going with is_shapes_initialized() could offer clarity:
As this displays all functions, now.
But how can using wrong grammar be a good approach? Shouldn't I just assume that the user should also ask IntelliSense for "are_initialized" or just look into the documentation in the first place? Probably not, right? Should I just give up on grammatical correctness?
The way I see it, a variable is a single entity. Maybe that entity is an aggregate of other entities, such as an array or a collection, in which case it would make sense to give it a plural name e.g. a set of Shape objects could be called shapes. Even so, it is still a single object. Looking at it that way, it is grammatically acceptable to refer to it as singular. After all, is_shapes_initialized actually means "Is the variable 'shapes' initialized?"
It's the same reason we say "The Bahamas is" or "The Netherlands is", because we are referring to the singular country, not whatever plural entity it is comprised of. So yes, is_shapes_initialized can be considered grammatically correct.
It's more a matter of personal taste. I would recommend putting "is" before functions that return Boolean. This would look more like:
bool is_time_initialized();
bool is_random_initialized();
bool is_shapes_initialized();
This makes them easier to find and search for, even if they aren't grammatically correct.
You can find functions using "are" to show it is plural in places such as the DuckDuckGo app, with:
areItemsTheSame(...)
areContentsTheSame(...)
In the DuckDuckGo app, it also uses "is" to show functions return boolean, and boolean variables:
val isFullScreen: Boolean = false
isAssignableFrom(...)
In OpenTK, a C# Graphics Library, I also found usage of "are":
AreTexturesResident(...)
AreProgramsResident(...)
In the same OpenTK Libary, they use "is" singularly for functions that return boolean and boolean variables:
IsEnabledGenlock(...)
bool isControl = false;
Either usage could work. Using "are" plurally would make more sense grammatically, and using "if" plurally could make more sense for efficiency or simplifying Boolean functions.
Here's what I would do, assuming you are trying to avoid calling this function on each shape.
void init_each_shape();
bool is_each_shape_initialized();
Also assuming that you need these functions, it seems like it would make more sense to have the functions throw an exception if they do not succeed.
what's the naming convention for a function that searches an entity by 4 parameters?
for instance GetCarByColourBrandStyleAndType sounds way too long although is descriptive enought IMO
Can't you just use SearchForCar for instance?
The paramaters (I expect are type, brand, color...) should give clarification? You can always make one or more parameters optional when you have for example another function saying GetCarByBrandColor()
Is it possible to create variables to be a specific type in Lua?
E.g. int x = 4
If this is not possible, is there at least some way to have a fake "type" shown before the variable so that anyone reading the code will know what type the variable is supposed to be?
E.g. function addInt(int x=4, int y=5), but x/y could still be any type of variable? I find it much easier to type the variable's type before it rather than putting a comment at above the function to let any readers know what type of variable it is supposed to be.
The sole reason I'm asking isn't to limit the variable to a specific data type, but simply to have the ability to put a data type before the variable, whether it does anything or not, to let the reader know what type of variable that it is supposed to be without getting an error.
You can do this using comments:
local x = 4 -- int
function addInt(x --[[int]],
y --[[int]] )
You can make the syntax a = int(5) from your other comment work using the following:
function int(a) return a end
function string(a) return a end
function dictionary(a) return a end
a = int(5)
b = string "hello, world!"
c = dictionary({foo = "hey"})
Still, this doesn't really offer any benefits over a comment.
The only way I can think of to do this, would be by creating a custom type in C.
Lua Integer type
No. But I understand your goal is to improve understanding when reading and writing functions calls.
Stating the expected data type of parameters adds only a little in terms of giving a specification for the function. Also, some function parameters are polymorphic, accepting a specific value, or a function or table from which to obtain the value for a context in which the function operates. See string.gsub, for example.
When reading a function call, the only thing known at the call site is the name of the variable or field whose value is being invoked as a function (sometimes read as the "name" of the function) and the expressions being passed as actual parameters. It is sometimes helpful to refactor parameter expressions into named local variables to add to the readability.
When writing a function call, the name of the function is key. The names of the formal parameters are also helpful. But still, names (like types) do not comprise much of a specification. The most help comes from embedded structured documentation used in conjunction with an IDE that infers the context of a name and performs content assistance and presentations of available documentation.
luadoc is one such a system of documentation. You can write luadoc for function you declare.
Eclipse Koneki LDT is one such an IDE. Due to the dynamic nature of Lua, it is a difficult problem so LDT is not always as helpful as one would like. (To be clear, LDT does not use luadoc; It evolved its own embedded documentation system.)
When I wrote some general programming utility code, I found that it's good to have both inplace mutator and new object creator member function for one functionality.
For example, some class which represents path in file system may have "normalize" functionality. Path object may mutates itself into normalized one, or returns new normalized path object.
class path {
...
void normalize_itself()
path get_new_normalized_path()
...
}
I've tried some convention for this one, but most of them are not satisfiable.
'normalize!' for inplace function like ruby - good, but most other languages don't support special character to be included in identifier.
'normalize_ip' for inplace function - since most of my function usages are inplace, I think it's too ugly.
'get_normalized' for non-inplace function - acceptable, but can be confused with other simple getter function for member.
'normalized' for non-inplace function - sometime not uniform, and easily confused with its inplace counter part.
write non-inplace function as free function - lack of intellisense assistance of IDE, sometime visibility issues.
I'd like to find some good/practical convention to distinguish two function.
I think normalize for your mutator and grab_normalized for your object creator would work.
In programming (and math) there are variables and constants. Is there a name to describe both of them?
I was thinking value, but that's not it. A value is what variables/constants contain, not what they are.
I would call it a symbol. From google:
sym·bol/ˈsimbəl/Noun
1. A thing that represents or stands for something else,
esp. a material object representing something abstract.
...
From what I know Its called a field
How about:
maths and logic: term
programming: l-value and r-value.
There are a few different terms I use, depending on context. I'll give you a list of the terms I (might) use - sometimes I'll just default to calling everything 'variables'.
Field - a variable or constant that's declared as part of the class definition.
Parameter - one of the inputs specified when defining a method in a class.
Argument - the actual value that you provide for a parameter when calling a method.
Method variable - a variable declared inside a method.
Method constant - a constant declared inside a method.
In OOP, the attribute can be both a variable and a constant.
Identifiers
In computer languages, identifiers are tokens (also called symbols) which name language entities. Some of the kinds of entities an identifier might denote include variables, types, labels, subroutines, and packages.
Symbols are super set of Identifiers
https://en.wikipedia.org/wiki/Identifier#In_computer_languages
How about "data item"?
One definition: https://www.yourdictionary.com/data-item
Example showing it can be used for local variables/constants as well (unlike "field" or "attribute"): https://www.microfocus.com/documentation/visual-cobol/VC222/EclWin/GUID-A3B817EE-1D63-4F67-A62C-61DE681C6719.html