TLDR Explains Code Like I Am Five
Written by Nikos Vaggalis   
Monday, 05 December 2022

TLDR is a plugin for the popular JetBrains IDEs that explains what a piece of code does in natural English. It's a big productivity boon for developers.

TLDR, although based on OpenAI's Codex, the model that's also powering GitHub Copilot, does not intend to help you write code or automate anything. Instead it attempts to decipher what a piece of code does by producing a narrative in natural English, saving hours when trying to read and comprehend it.

As programmers, one skill that must be mastered is reading code. This is manifested in a variety of ways:

  • A student trying to understand an assignment
  • A beginner or senior trying to learn a new language
  • Understanding code to refactor it
  • Understanding code to use it for your own
  • As part of a Code review or QA
  • When inheriting an unknown or legacy codebase
  • When the software house is handed in a code base which is the product of the outsourcing to a third party

Code generation is nothing new to the world of programmers; it was  there even before the advent of Windows Forms or Macromedia Dreamweaver; drag and drop your GUI elements on a visual plane and get the code generated, ready to be deployed in production.

The other way around, generating specifications from code is already a thing too; check Swagger for instance which generates OpenAPI definitions from existing (Java) APIs code.

The next step in the evolution ladder subvened by the recent achievements of AI is assisted coding. Intelligent code completion, documentation and code searching across multiple sources, auto completing incomplete code and revealing syntax errors as you go.

And then, there's Github Copilot. Based on OpenAI's Codex, an AI system that is a descendant of GPT-3, was trained on massive amounts of data that contain both natural language and billions of lines of source code from publicly available sources.

Copilot is a game changer as it can interpret natural, albeit simple, language, to write fully blown working code on the user’s behalf. That is unlike other code completion tools which suggest one-liners, Copilot generates entire functions. Copilot can:

  • Generate code snippets based on code comments and the function's name. 
  • Understand other languages beyond English
  • Write unit tests, visual regression tests, generate Mock data
  • Give suggestions when writing regexes
  • With aid of the Copilot Labs extension, developers can translate code from one programming language to another,
    as well as get an explanation of its inner workings in plain language. 

This last feature is still in an experimental stage and available only as a VS Code extension for the time being.

If you are a Jetbrains fan, there's TLDR, a plugin compatible with the Jetbrains range of IDEs, based on the same model as Copilot and the same explaining code abilities. Saying that, it would be very interesting for someone to produce a side by side comparison of both of those tools, to check which has the best outcomes when applied on the same piece of code.

One test I run on TLDR was with Intellij Community edition and Java. Having seen the demos (on PHP) and trying it myself on some Core Java snippets I can say that the results were pretty good. Then I decide to explore its wider potential. Would it also be applicable to code dependent on third party library imports or frameworks?

So I applied it on an under-development Vaadin/Spring Boot based app. I first analyzed a short Vaadin snippet of creating a Login View:

public LoginView(){
  add(new H1("Hello"), login);

This is what it gave me back:

 You can't possibly read this so here's a transcription:

  1. We add a class name to the view. This is used for styling purposes.
  2. We set the size of the view to full, which means that it will take up all available space in its parent component (in this case, the UI)
  3. We align items in this view to be centered both horizontally and vertically.
  4. The login button has an action called "login". This is used by Vaadin Flow to know what should happen when a user clicks on it (more on that later).
  5. Finally, we add two components: an H1 element with text "Hello" and our login button component from earlier (which contains a TextField and PasswordField), 

Then I thought that it would be interesting to try it on Spring security configurations which are notoriously hard to get right and decipher their meaning.

.requestCache().requestCache(new CustomRequestCache())
.defaultSuccessUrl("/homepage", true)

(For the curious, I disable the csrf protection of Spring Security as Vaadin handles it internally.)

This is the transcription of the result:

  1. We disable CSRF protection.
  2. We allow all requests to the URL which is where our Vaadin application will be served from.
  3. We configure a custom request cache that stores unauthorized access attempts and redirects the user after login to the originally requested page (or to a default one).
  4. We allow all internal framework requests (e.g., for static resources).
  5. All other requests need to be authenticated, except for the ones that match our login page URL and our Vaadin servlet URL (/login and /vaadinServIet respectively).
  6. The login form should be served from /login, should use HTTP POST method, and should submit username/password parameters with names. The failure url is "/login?error", which maps to an error view in LoginView class (see below). After successful authentication we redirect back to "/homepage" or whatever was requested initially by the user before being redirected into this filter chain due to an unauthenticated request (/homepage is mapped in MainView class - see below).

One observation though...  I don't know what "(more on that later)" or "- see below" refer to.

I can say, that it was spot on! Very very impressive indeed... next time I stumble upon on such a security configuration one-liner, I know where to turn to. However I couldn't try it on more snippets because the free version is limited and allows you just two attempts per day. I will have to wait for tomorrow to run another two, perhaps on a more elaborate piece of code, or what about  a complex regular expression?

The deal here is that reading code is much more difficult to do than writing it and an assistant like this is going to prove valuable in reducing the time you need to comprehend it.

One concern that I have regarding both Copilot and TLDR, is that of privacy, since they both expose an API which is called upon with your code as the payload. The AI to interpret your code lives on their servers after all. I haven't gone through their privacy policies and I'm pretty sure that there aren't any malevolent spying clauses but one who wants to use their products in production should first check.

At the end of the day, the question is, what does the future hold for programmers? Are we doomed as a profession? Will AI take our jobs too?

OpenAI's ambitions in the long term do not stop at Copilot or TLDR; they want users to employ natural language to control APIs. This would be immensely beneficial in for example querying databases the same way we do with search engines like Google;type a sentence in your mother language to query a database instead of writing SQL. This will not only help data professionals in creating reports and dash boards faster but it will also make it feasible for non technical users to get access to the source data.

The story of coders' jobs being obliterated is not new. It has been told many timeds before even before the advent of AI. The villains were  the low code and the no code tools;they would make coders redundant.

But the difference lies between the terms coder vs software engineer. Coding might be threatened but engineering software is not. Engineering software means understanding and refining requirements, translating business logic, thinking architecturally,
going back to the drawing board, connecting the dots, testing, debugging, deploying, optimizing.

Instead I suggest looking at these as tools that will increase productivity just like the Windows Forms GUI generator did.
Certainly I could have created my Buttons or Checkboxes in code, but if I can do it faster when using a GUI tool why not?.
So now not only is my productivity increased, I can also free myself from the tedious parts of my job to focus on the more important aspects like translating and validating business requirements.

High level languages like Python or Java make programming easier and more accessible to more developers, than when there was with just C. These tools aim to do the same. High level languages did not reduce jobs, they increased them.

In conclusion, the key here to realize is that an AI can't cope with the reasoning and wide range of skills required in engineering software. But it can undoubtedly be a useful aid.

For the time being enjoy TLDR.

More Information

TLDR on Jetbrains Marketplace

Related Articles

Codex - English To Code

GitHub Copilot Provides Productivity Boost 

GitHub Copilot - Your Programming Pal

What Ruins A Developer's Day  


Last Updated ( Friday, 01 September 2023 )