In Flex I can specify a * as datatype.
What is it and how should I use it.
I've written a inArray() method that takes as argument something to search for and something to search in. The "something to search for" looks like a great candidate for the * datatype.
Should I not use it?
Thank you.
* indicates an untyped identifier. You'd use it when you can't guarantee that the type of an object will conform to any specific class or interface definition.
Whether * is appropriate in your example depends on what operations you use in your search. If you just rely on common equality operations, you should be fine, and in fact it would probably be the best choice.
The * is to AS3 as Object is to Java. See the following:
http://livedocs.adobe.com/flex/3/html/help.html?content=03_Language_and_Syntax_11.html
The * actually explicitly says, that something has no type. In fact it's the default type, all untyped variables or functions fall back to.
It basically tells the compiler: "I don't want you to perform any typecheck on this, because this simply gets handled at runtime".
In fact * is no type. There is simply no value corresponding to it.
Please note, that only expressions of type * can return the value of undefined. Anything, that is of type Object (i.e. anything that is of a different type, than no type), can only hold null.
You will see that many Array methods use that type. That's specifically, because Array elements are of no type and can thus be undefined.
Therefore, I suppose you could have a slight performance difference based on whether your parameter is typed * or Object (or whether you use strict comparison or not, for that matter).
Personally, I would advise you use * in this case, mostly, because it is consistent with Array methods.
you have to use * when strict mode of compilation is enabled. It's just 'no type', and it will be checked at runtime.
Related
I was creating a function and I tried to increase the value of the parameter which was declared as Integer. But it said that the value of that parameter can not be reassigned. I am a beginner so if I am missing some concept please tell me.
Yes, in Kotlin function parameters can't be changed.
(However, if they refer to mutable objects, then those objects can change. For example, if you declared fun a(b: List<String>), then you could add another String to the List; but you couldn't set b to refer to a different List.)
This is different from Java, where parameters are variable (unless specified as final).
This behaviour was announced in Kotlin milestone M5.1, where it was explained as avoiding confusion (especially in constructors), and promoting good style.
See also this answer.
Is it possible to remove the last element from a tuple in typesafe manner for arbitrary arity?
I want something like this:
[A,B,C] abc = [a,b,c];
[A,B] ab = removeLast(abc);
No, unfortunately it's not possible, the reason being that a tuple type is represented within the type system as a linked list of instantiations of Tuple, but the type system can't express loops or recursion within the signature of a function. (And having loops/recursion would almost certainly make the type system undecidable.)
One way we could, in principle, solve this in future would be to have a built-in primitive type function that evaluates the last element type of a tuple type.
By "primitive" type function, I mean a type function that can't be written in the language itself, but is instead provided as a built-in by the compiler.
Ceylon doesn't currently have any of these sorts of primitive type functions, but there are a couple of other similar problems which could be solved in this manner.
How do I make PhpStorm suggest input variables ?
In Java/C# and the like (with VS/Eclipse), when I have a function that receives enum-input-variable, like:
void func(SomeEnum var);
Whenever I type func(, the editor kindly suggests all the available enums (of type SomeEnum). I look for this same functionality in PHP, when I have a predefined set of input options (like DB's tables).
Maybe with the use of Intellilang or these # tags (PHPDocs ?) I can predefine such list ?
Currently you cannot limit the possible options for code completion in this regard: PHP simply has no such "thing" similar to Enum. The only limitation you can do is limit by expected parameter type (e.g. int variable will not be offered when parameter expects an array).
I think this will be the correct ticket to look for: http://youtrack.jetbrains.com/issue/WI-854 and maybe http://youtrack.jetbrains.com/issue/WI-3623
Kind of related (for array indexes completion): http://youtrack.jetbrains.com/issue/WI-3423
I was looking at some code of a fellow developer, and almost cried. In the method definition there are 12 arguments. From my experience..this isn't good. If it were me, I would have sent in an object of some sort.
Is there another / more preferred way to do this (in other words, what's the best way to fix this and explain why)?
public long Save (
String today,
String name,
String desc,
int ID,
String otherNm,
DateTime dt,
int status,
String periodID,
String otherDt,
String submittedDt
)
ignore my poor variable names - they are examples
It highly depends on the language.
In a language without compile-time typechecking (e.g. python, javascript, etc.) you should use keyword arguments (common in python: you can access them like a dictionary passed in as an argument) or objects/dictionaries you manually pass in as arguments (common in javascript).
However the "argument hell" you described is sometimes "the right way to do things" for certain languages with compile-time typechecking, because using objects will obfuscate the semantics from the typechecker. The solution then would be to use a better language with compile-time typechecking which allows pattern-matching of objects as arguments.
Yes, use objects. Also, the function is probably doing too much if it needs all of this information, so use smaller functions.
Use objects.
class User { ... }
User user = ...
Save(user);
It decision provides easy way for adding new parameters.
It depends on how complex the function is. If it does something non-trivial with each of those arguments, it should probably be split. If it just passes them through, they should probably be collected in an object. But if it just creates a row in a table, it's not really big deal. It's less of a deal if your language supports keyword arguments.
I imagine the issue you're experiencing is being able to look at the method call and know what argument is receiving what value. This is a pernicious problem in a language like Java, which lacks something like keyword arguments or JSON hashes to pass named arguments.
In this situation, the Builder pattern is a useful solution. It's more objects, three total, but leads to more comprehensible code for the problem you're describing. So the three objects in this case would be as such:
Thing: stateful entity, typically immutable (i.e. getters only)
ThingBuilder: factory class, creates a Thing entity and sets its values.
ThingDAO: not necessary for using the Builder pattern, but addresses your question.
Interaction
/*
ThingBuilder is a static inner class of Thing, where each of its
"set" method calls returns the ThingBuilder instance being worked with
while the final "build()" call returns the instantiated Thing instance.
*/
Thing thing = Thing.createBuilder().
.setToday("2012/04/01")
.setName("Example")
// ...etc...
.build();
// the Thing instance as get methods for each property
thing.getName();
// get your reference to thingDAO however it's done
thingDAO.save(thing);
The result is you get named arguments and an immutable instance.
Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of "value limits" as well as the classic documentation ?
Note: I am not talking about comments within the code
By "value limits", I mean:
does a parameter can support a null value (or an empty String, or...) ?
does a 'return value' can be null or is guaranteed to never be null (or can be "empty", or...) ?
Sample:
What I often see (without having access to source code) is:
/**
* Get all readers name for this current Report. <br />
* <b>Warning</b>The Report must have been published first.
* #param aReaderNameRegexp filter in order to return only reader matching the regexp
* #return array of reader names
*/
String[] getReaderNames(final String aReaderNameRegexp);
What I like to see would be:
/**
* Get all readers name for this current Report. <br />
* <b>Warning</b>The Report must have been published first.
* #param aReaderNameRegexp filter in order to return only reader matching the regexp
* (can be null or empty)
* #return array of reader names
* (null if Report has not yet been published,
* empty array if no reader match criteria,
* reader names array matching regexp, or all readers if regexp is null or empty)
*/
String[] getReaderNames(final String aReaderNameRegexp);
My point is:
When I use a library with a getReaderNames() function in it, I often do not even need to read the API documentation to guess what it does. But I need to be sure how to use it.
My only concern when I want to use this function is: what should I expect in term of parameters and return values ? That is all I need to know to safely setup my parameters and safely test the return value, yet I almost never see that kind of information in API documentation...
Edit:
This can influence the usage or not for checked or unchecked exceptions.
What do you think ? value limits and API, do they belong together or not ?
I think they can belong together but don't necessarily have to belong together. In your scenario, it seems like it makes sense that the limits are documented in such a way that they appear in the generated API documentation and intellisense (if the language/IDE support it).
I think it does depend on the language as well. For example, Ada has a native data type that is a "restricted integer", where you define an integer variable and explicitly indicate that it will only (and always) be within a certain numeric range. In that case, the datatype itself indicates the restriction. It should still be visible and discoverable through the API documentation and intellisense, but wouldn't be something that a developer has to specify in the comments.
However, languages like Java and C# don't have this type of restricted integer, so the developer would have to specify it in the comments if it were information that should become part of the public documentation.
I think those kinds of boundary conditions most definitely belong in the API. However, I would (and often do) go a step further and indicate WHAT those null values mean. Either I indicate it will throw an exception, or I explain what the expected results are when the boundary value is passed in.
It's hard to remember to always do this, but it's a good thing for users of your class. It's also difficult to maintain it if the contract the method presents changes (like null values are changed to no be allowed)... you have to be diligent also to update the docs when you change the semantics of the method.
Question 1
Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of "value limits" as well as the classic documentation?
Almost never.
Question 2
My only concern when I want to use this function is: what should I expect in term of parameters and return values ? That is all I need to know to safely setup my parameters and safely test the return value, yet I almost never see that kind of information in API documentation...
If I used a function not properly I would expect a RuntimeException thrown by the method or a RuntimeException in another (sometimes very far) part of the program.
Comments like #param aReaderNameRegexp filter in order to ... (can be null or empty) seems to me a way to implement Design by Contract in a human-being language inside Javadoc.
Using Javadoc to enforce Design by Contract was used by iContract, now resurrected into JcontractS, that let you specify invariants, preconditions, postconditions, in more formalized way compared to the human-being language.
Question 3
This can influence the usage or not for checked or unchecked exceptions.
What do you think ? value limits and API, do they belong together or not ?
Java language doesn't have a Design by Contract feature, so you might be tempted to use Execption but I agree with you about the fact that you have to be aware about When to choose checked and unchecked exceptions. Probably you might use unchecked IllegalArgumentException, IllegalStateException, or you might use unit testing, but the major problem is how to communicate to other programmers that such code is about Design By Contract and should be considered as a contract before changing it too lightly.
I think they do, and have always placed comments in the header files (c++) arcordingly.
In addition to valid input/output/return comments, I also note which exceptions are likly to be thrown by the function (since I often want to use the return value for...well returning a value, I prefer exceptions over error codes)
//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);
#Fire Lancer: Right! I forgot about exception, but I would like to see them mentioned, especially the unchecked 'runtime' exception that this public method could throw
#Mike Stone:
you have to be diligent also to update the docs when you change the semantics of the method.
Mmmm I sure hope that the public API documentation is at the very least updated whenever a change -- that affects the contract of the function -- takes place. If not, those API documentations could be drop altogether.
To add food to yours thoughts (and go with #Scott Dorman), I just stumble upon the future of java7 annotations
What does that means ? That certain 'boundary conditions', rather than being in the documentation, should be better off in the API itself, and automatically used, at compilation time, with appropriate 'assert' generated code.
That way, if a '#CheckForNull' is in the API, the writer of the function might get away with not even documenting it! And if the semantic change, its API will reflect that change (like 'no more #CheckForNull' for instance)
That kind of approach suggests that documentation, for 'boundary conditions', is an extra bonus rather than a mandatory practice.
However, that does not cover the special values of the return object of a function. For that, a complete documentation is still needed.