IntelliSense - illusion of knowledge

Irrelevant at this point

I had the idea for this one for a long time and I want it out of my head even tho it might be irrelevant now.

It's about...

...code completions in general, but the smart ones. The simple text editor's word completions which just search for similar words are fine and not under investigation here. I'm talking about those kind of code completions which try to figure out the type of the variable, namespaces and included libraries to show only valid suggestions - and typically with a little docs like parameter names etc.

The first time I encountered those was in Visual Studio which named the feature IntelliSense. And that's also where I first saw the issue I want to describe. Today it's wide spreaded feature of any LSP enabled editor.

The situation

I was working remotely and we had a couple of new hires in the company. It took a few months until I visited the office and saw them working. Whenever they tried to do anything with an object they would type it's variable name, press dot . and then CTRL + SPACE to get the IntelliSense code completion list of possible properties and methods.

So far so good. Nothing wrong with that. After all that's what it's for and it is an useful tool to speed up the work. But that was not the reason they were using it.

This list was the only source of information they had about those objects. They would slowly read it, item after item, trying to figure out which method might do the thing they need to do, judging only by their names. And if they were unsure if they should use list.count property or list.count() method or maybe list.capacity they would simply try it once and see if the result matches their expectation.

The issue

Those new programmers were just two or three years younger than me. But the difference was enough so that the environment they learned in already had those tools when they started. They actually never read or even saw a documentation, read a book or the source code of the things they were trying to use in their code.

They had no idea what they were doing. When I asked if they know what the methods and properties they were using do, they straight up said that they don't, that they are just trying things out until they work. I asked if they know how to find those things in the documentation and they didn't.

Same applied to classes and function from our own codebase. The used the same method to "learn" what was there without actually understanding what any of those things did. They had access to the source code and many of our stuff was nicely annotated with documentation comments.

They thought that they knew how to program but without IntelliSense code completion they couldn't do anything. They only had the illusion of knowledge.

Why it's a problem

Making this partial information easily accessible made it so that less and less programmers would put the effort to find out the needed information in the documentation. But it contained the crucial details that do not fit in the functions or property names. Nuance that makes the difference between code that works and code that mostly works.

Searching for the information was tedious and time consuming but every time one would learn something new by accident, often unrelated but that would increase their knowledge and understanding helping with future problems. Besides documentation often contained more than just raw explanation of function parameters and returned value. It would explain ideas, expected usage, had examples, references to other functions and properties that might be related and useful. You cannot get that with even the best code completion.

Next generation

This created whole movement of long and descriptive method and variable names. People started expecting and requiring that the code should be "self explanatory". They would say that the comments explaining what function does and returns were bad. C style function names were ridiculed as those were impossible to figure out without reading docs - which no one wanted to do anymore.

Also no one expected anyone to remember any of the APIs they were using. My new colleges were unable to even talk about their code as they didn't remember the names of the functions and parameters they were using. New programmers were told that they should not know the implementation details of anything they were using. That the "names" is all they need - but since they were using auto-completion they only knew a couple of first letters + TAB.

I think that this made the object oriented languages more popular as this functionality was very convenient with the variable DOT function kind of syntax. Programming languages with functions not related directly to one type are not that easy to work with in that manner.

Disclaimer

Don't get me wrong. Function names should make sense. But it's impossible to expect that their entire nuance can be expressed solely via names. Also I don't expect anyone to remember entire API of the system they are working with. But knowing most of it and what possibilities there are was a sign of an expert. Getting to that knowledge only via code completions is not possible.

Let's follow the Hermione's example and do some light docs reading from time to time.