I personally find the lack of well structured and guided reference manual to the language a very bumpy hurdle towards my journey of liking the language in the first place.
True that there are a lot of similarities with Java, however, with every new thing we start with the basics. I have an overall feeling of a freshman attempting his first uni assignment.
The following is sharply lacking:
List of keywords, their description, their usage, examples of all possible usages and contexts
Reserved words, their description, their usage, examples of all possible usages and contexts
(E.G. What is an âitâ, where it came from, where is its significance, what are the scopes, and finally can it be used as a generic modifier outside of its context of significance?
Or Where did the listOf, mapOf come from? Are there any others? How to correctly structure them?
This list of âmatryoshka dollâ riddles is very long)
Inconsistency of marking structures, such as â. .â for up to, but verbatim âdownToâ for down to. Wouldnât it be clear from the context 1. .9 is up to 9. .1 is down to? Anyone that is interfacing with programming should know basic mathematical notations [1. .9] - closed range of 1 to 9, [1. .9) semi-open range of 1 to 9, (1. .9) open range of 1 to 9. And it really doesnât matter if in the expression [m . . n] m > n or n < m, the direction can be set runtime from the context, [m . . n, 2] could mean from m to n with steps of 2.
Overall the language lacks consistency.
Non-deterministic variants of the same construct.
E.G. list?.size ?: Exception
Wouldnât it be a better and clearer notation to write list ? list.size : Exception or list ? list.size if we only care for the non null part.
I personally find my learning curve to be too steep without an expert at hand that Iâd grill for the details that would make my perspective of Kotlin clearer. We are in an age when newer means better⌠This is not better than JavaâŚ
2.5: listOf, mapOf and other variants are one of the many of Kotlinâs top-level declarations. They can be accessed and invoked in the code without specifying the file name whence it came from, like global functions. More on that in the function reference.
3:
Personal opinion, but I donât feel like that is an inconsistency, granted that downTo does look a bit out of place. Itâs a straightforward approach that requires you to specify how you want the range to behave during iteration.
4:
Kotlin lacks the ternary operator; in return, Kotlinâs if statements can act as expressions when needed.
list?.size either returns the list size or null if the list is null. The null-coalescing operator ?: returns the left operand if it is not null else the right operand.
Personally, I find that the ?. approach is extremely nice and readable for chaining long methods and property calls. Multiple chains of obj ? obj.prop ? obj.prop.prop ? obj.prop.prop.prop wouldnât look too nice. However, obj?.prop?.prop?.prop is certainly more concise and readable.
1 and 2
autogenerated list is not sufficient. It lacks descriptions.
Assume no knowledge of other similar languages and describe each keyword in detail as if producing a book for print. The mere fact that the references are through S/O is already not flattering. It has to be clearly visible from the official language reference.
Grammar reference - imagine you go to a restaurant and order a stake. Youâd be quite disappointed if they give you the meat and tell you to cook the stake yourself. Thatâs my feeling right now with the grammar reference.
2.5:
Function reference give no clue of the comprehensive list of all of those top level functions and their correct usage. What is that implicit Object or that implicit java.lang equivalent that lists all possible ready-to-use constructs?
Why was Java so successful in uptake even though it came long after C/C++?
Simple, concise, clear, one way of doing one thing approach, less cryptic, small basic knowledge requirements, if it is clear from the context than no need to explicitly write or define.
This is still an unbaked language. It may have addressed some pain points in other languages but has clearly created a whole stack of new pain points for its users.
Iâd rather type a few extra lines in Java then try to decrypt undocumented language.
I think that kotlin is to young to have very good documentation. Especially since language is still changing.
The Oracle documentation is a bad example. Mostly all of it is very hard to read. As for learning curve, kotlin takes not only after java, but also after some more modern languages. I can say, that it is much easier to learn if you have Java 8 an Groovy experience.
Your critic is valid, but youâre confusing 2 different things. .. is the rangeTo operator, which defines a simple range (with a minimum and maximum). Iteration direction and step size isnât part of the Range class, when youâre using downTo or step, youâre just creating a sequence of Ints or whatever. A Range on the other hand doesnât need to be iterable. You can also write "Adam".."Eve" and have a range that includes all the Strings in between.
Thereâs nothing non deterministing about this, val s = list?.size ?: throw Exception() is just an optimized shorthand form of the Java analogue
Integer tmp = (list == null ? null : list.size()); // list?.size
if (tmp == null) throw new Exception(); // ?: throw Exception()
int s = tmp; // val s = ...
Kotlin does actually have a formal specification though itâs still in draft and, given the number of TODOs, very much a âwork in progressâ. Even so, it does answer some questions about hard and soft keywords.
Personally, I think the Kotlin documentation is quite good for a nascent language and an attempt has clearly been made to write it in an intelligible fashion which has enabled many people to get up and running in the language after only a few hours of study. Sure, it assumes you have some knowledge of Java or other object oriented languages but I think thatâs fair enough as the language would be unlikely to appeal to a complete newbie at this stage of its development.
It also helps considerably to have a copy of the âKotlin in Actionâ book to hand as this was written by two of the Kotlin team developers.
Of course, there are many points which are unclear (weâve just had one regarding the equals() method in another thread). However, I suspect that things will improve markedly when the Kotlin Foundation is established as Google experts will then be able to help out JB with both the formal and informal documentation.
Personally, I donât dislike the 'downTo' function as it makes it clear at a glance that one is iterating in a downwards direction. I also like the 'until' function for cases where the endpoint of the range is exclusive - much better to my eye than squiggles such as ..< that you find in some other languages.
We really do not believe that an alphabetic list of keywords is the most useful way to organize the documentation of a language. When learning a foreign language, you donât start with reading the dictionary from A to Z, or the grammar reference showing all possible noun forms or tenses, but instead start with learning how to say âhelloâ and âgood byeâ. Similarly to that, for your first steps in Kotlin, weâve provided a basic syntax overview and a list of idioms. We believe that starting with these is a far more productive way to learn the language compared to trying to look at all possible usages and contexts of the âoutâ or âbyâ keywords.
I disagree, weâre not learning a foreign language here, we are learning a new mathematical structure with its axioms (basic, indivisible blocks of the programming language) and its set of rules (how to put the basic blocks together, aka the grammar of the programming language), which together help us prove theorems (aka write programs).
As a JetBrains team developer, you are exposed to considerably more details and have a birdâs eye view of the works⌠Other developers however donât have that. The only way of getting the missing information is through well defined, complete documentation.
Understandably, Kotlin is a new construct, it is still a fledgeling language. Even so, if one doesnât know full potential for each building block of the language, it is more than likely they are either going to underutilise the language and become detractors or misuse the language and end up abandoning it completely.
At this stage you have conquered the early adopters (possibly 13%), you still need to win over the early and late majority group of the users (another 70%) to be successful.
They will at some stage require from you what I set out in my initial comment - comprehensive dictionary and grammar book.
Next, should be the reserved words. In this case, the top level functions or objects or anything else that can be used without import or preparation and what not.
List these reserved words, define their scope, provide usages, detail the pre and post conditions, provide variations.
This page documents all the âreserved wordsâ. listOf and such are not reserved words; they are standard library functions, and the standard library reference is already available. The list of standard library packages that can be used without import is also provided in the documentation.
In general it is true rangeTo is not necessarily interable but for integral numbers rangeTo is Iterable.
5 downTo 1 is an expression of IntProgression type that defines an iterator. 1 ⌠5 is of type IntRange which is a subclass IntProgression so also is iterable.
