Bring back the Turbo Pascal IDE!

I began programming in the early 90's using Turbo Pascal, apart from learning how to program in the absence of the Internet it was a great experience. Turbo Pascal was an well made product created by Borland Software Corporation, it was a complete Integrated Development Environment which included the editor, the compiler, the debugger, and the language documentation. Turbo Pascal had all the features I needed.

It run in MS Dos and it was fast. Turbo Pascal built for the Pascal language, it was not a generic IDE that can work with many languages. The applications I wrote were all MS Dos based, and I wrote everything from scratch.

source: softportal.com

There was no Stackoverflow, I had no Internet, so the only help was through books, trial and error, and the Turbo Pascal help system… which was actually very good. Later, as I matured, I moved to Turbo C++, which was just like Turbo Pascal but with C++ integration.

TL;DR

My JavaScript Environment:

• Editor: Atom, with the following plug-ins: atom-beautify, atom-ternjs, docblockr, linter, linter-eslint, minimap, minimap-highlight-selected.
• Unit testing: tape, in a nutshell it’s simple.
• Code comments: JSDocs with documentation.js to generate Readme.md.
• Static analysis tool: ESLint (based on AirBnB style) with JSDoc plug-in for basic checking and style enforcement. FlowType via flow-jsdoc.

Jump to 2017

It’s 2017 and I wish I had Turbo Pascal… at least it’s simplicity. Today there are numerous editors and IDEs to create and edit your code. Some of these are Aptana, Atom, BBEdit, BlueFish, Brackets, Cloud9, Coda, CodeRunner, CoffeeCup, Eclipse, Emacs, Espresso, Expression, Geany, Netbeans, Notepad++, Notepad2, Komodo IDE, SlickEdit, Sublime Text, TextMate, Visual Studio, WebStorm, VIM, UltraEdit, just to name a few popular ones. I have extensively used Atom, Sublime Text, WebStorm, and Vim for JavaScript and I am currently using Atom most of the time.

I think I’m suffering from JavaScript editor fatigue.

Below are my own needs for a JavaScript editor today:

1. Pure JavaScript: Be able to write code in Vanilla.js where possible and to target the oldest supported version of Node.js, today that’s version 4.8.0. I’m not particularly a fan of code transpilers and I don’t need the latest an greatest JavaScript features.
2. Autonomous documentation: Be able to write my code comments such that it completely generates the documentation as a Readme.md file.
3. Static Analysis: Be able to use a JavaScript static analysis tool to give me hints where my code may be broken and to nag me to use a particular coding style.

Vanilla.js

I’ve always been a fan of the Vanilla.js JavaScript framework. Just in case you don’t get it, Vanilla.js is just JavaScript without any frameworks… and in my view a pure JavaScript without any transpiling. Over time, I have tried various transpilers and languages such as Dart. Each time I have reverted back to Vanilla.js for the simple reason that it was just simpler. I found that with transpilers it could be difficult to find an error because the errors were obscured in code that I did not directly write and the source map was not immediately available. And I don’t see the point of transpiling Node.js code if it’s just going to be run on the server. I have also tried the Dart language for web development, it was a pain, I won’t go there.

I write JavaScript and C/C++ code for embedded devices like the BeagleBone and devices that support Espruino. To run JavaScript on the BeagleBone you need BoneScript runs node and currently it’s a very old version (v0.12), but that will update to v4 or v6 soon. Espruino is a micro version of JavaScript that runs on devices with as little as 128kB of RAM. It supports most of ES5, some ES6 and a few ES7 features.

So I have set my lowest common denominator is the oldest stable version of Node.js. Currently this is version 4.8.0. My IDE needs to have tools which support Node.js v4.8.0.

The Atom editor does all flavours of JavaScript very well, but it can be slow to open large files.

Documentation from Code Comments

For the code I keep, I like it to be well documented using code comments. However, because most of my audience is technical I also need to create technical documentation that explains the API.

JSDoc is a markup language used to annotate JavaScript source code files and docblockr is the Atom plug-in to help you write in JSDoc style.

Example of JSDoc with syntax highlighting using the docblockr Atom plug-in.

docblockr allows you to quickly add code blocks, type in /**[enter] and the code block will appear. Nice. And it’s usable.

Once the code comments are written it would be good to use these to generate the final documentation. And you can do this with documentation.js, a command line tool to convert your JSDocs into technical documentation in the following formats: HTML, Markdown, JSON.

Simply run this command to create the Readme.md file:

documentation build index.js --markdown-toc false -f md -o Readme.md

It’s a bit more complicated than that, you may want to add examples, like the one below.

JSDoc syntax in the code

JSDoc converted to

JavaScript Static Analysis

One of the great things about JavaScript is that you can throw any type at it and it will handle it, somehow. BUT that comes with a danger too, it will often handle it in predictable ways. I love this perverse nature of JavaScript, it makes it almost uncontrollable. Like a good racing car driver who is in-control while the car is out-of-control.

JavaScript static analysis brings some sanity to the JavaScript ‘race track’. A static analysis tool will parse your code without running it and detect potential bugs. A useful static analysis tool will give you warnings as you write your code. They can be generalised into two buckets:

• Style enforcement / Linter: these superficially check code and the code structure and suggest improvements. They follow predefined styles which are known (or assumed) to reduce bugs and improve readability. There are a few, the most popular by far is ESLint (I highly recommend this), others are JSHint and JSLint.
• Static type checker: This will do a deeper analysis of your code and use type inference to determine what types you have. These are good at detecting bugs you wouldn’t find with a linter, but they don’t really care much about style. Popular ones are Flow and the linter within the Google Closure Compiler.

I use ESLint to lint my code and the eslint-jsdoc-plugin to lint my comments. ESLint comes with many styles to choose from. These style guides determine everything from indentation size to avoiding unused variables. I took the AirBnB style guide and adapted it. ESLint is also available in Atom and provides useful inline comments, like below:

Example of ESLint error in the code

The Google Closure Compiler uses a mangled version of JSDocs (why did they do this). I won’t go on. I gave up pretty early.

Source: xkcd.com

The static type checker required a bit more investigation. With both Flow and Google Closure Compiler you have to declare variable types to ensure the type checker works. Not all variables need to be declared, since types can be inferred. Flow has a unique syntax for variable declaration which is not Pure JavaScript, but you can use comments, but I find that more difficult to read.

Flow comparison

There is a tool called flow-jsdoc that converts JSDoc code comments to Flow variable annotation. It’s still work in progress, but it works. This means using some scripts I can check my code for comments.

flow-jsdoc -f index.js > annotations/index.js; flow annotations/index.js

A static type checker saves you time. Really. You don’t need to declare the type of each variable. What I think is a good thing to do is to declare all the external facing variables and functions in detail. This means that in most cases the internal functions and variables the types can be inferred.