Developer productivity and code quality can be improved by using of an IDE (Integrated Development Environment). For developers who are not invested in an existing IDE, this document covers a few options that emacs, vi, textedit, etc... developers would benefit from investigating.
Along with the editors themselves, we discuss recommended plugins to that help developers with style checking and basic static analysis, integration with Github, autocompletion and similar tools that make development easier and more pleasant for individual developers, as well as promote best practices across KBase.
This section deals with the coding style standards for various languages. This is a living document and will expand over time as we discover what works best for the overall KBase developer community.
For Python, our standard is Python 3.6.x and the use of flake8 to enforce PEP8/pycodestyle and pyflakes on new code. This will require that developers install the python package flake8 via pip. We also highly recommend the use of virtualenv and optionally virtualendwrap. This article provides an overview of both tools: http://docs.python-guide.org/en/latest/dev/virtualenvs/
If installing pip, you can install flake8 in the "global" environment:
pip install flake8
The standard for new code is that flake8 should generate no warnings or errors - it is not necessary to make legacy code flake8 compliant.
Flake8 has configuration files per user, and per project. Flake8 configurations are distributed with KBase repos in the flake8 section of tox.ini files. We use tox.ini files in projects because tox is used for centralizing configuration of python code projects including test harnesses. Keeping it in all in a single file make managing these configurations more manageable.
Flake8 has a small collection of extensions - we make use of the putty extension. This enables fine grained control over how flake8 is applied to different files, and it is used in the flake8. Install this by:
pip install flake8-putty
The only current exception to the base set of flake8 rules is to allow line lengths up to 100 characters in length. The 80 character limit is something of an artifact of 80 column terminals, typewriters, etc... however extremely long lines do make code hard to read, so we allow up to 100 characters.
Here is an example project tox.ini configuration (for the kb_sdk repo) that extends the allowed line length to 100 characters and tells flake8 to ignore certain warnings that arise in the generated by KBase type compiler, warnings about legacy code from before flake8 as well as some irrelevant warnings that come about from the conventions used in init.py files:
[flake8]
max-line-length = 100
exclude =
# src/,
scripts/*,
modules/*,
test/*,
kbase-extension,
nbextensions,
node_modules
putty-ignore =
src/*/__init__.py : F401,E126
Javascript is a rapidly evolving standard, and luckily there are reasonable tools. The standard for KBase javascript development is eslint. It will be necessary to install nodejs and npm in order to install eslint. For MacOS users, we recommend using homebrew to install nodejs/npm.
Once npm is installed, this set of instructions can be run: http://eslint.org/docs/user-guide/getting-started
We recommend that developers who do not have an investment in other IDEs try to use either atom or Visual Studio Code. Both of these editors are free, multi-platform (MacOS, Windows and Linux) and have strong support for plugins from the community as well as well funded corporate sponsors (Github and Microsoft). They integrate well with Github as well as tools for KBase's major language platforms ( Python, Java, JS). Another option that is well loved by many developers is Sublime Text, however it is not free, and nags about payment unless it is licensed.
Atom is a popular free, open source editor with a large community of supporters, in addition to it's corporate sponsor, Github. It can be extended via JS code, as well as having a fairly huge pool of plugins and themes. The drawback is that it can be slow at times. When using Atom, we recommend installing the following plugins:
- linter
- linter-flake8 - this linter does not seem to honor per project tox.ini files properly - more info as we work out the details
- linter-eslint
- git-plus
- minimap
- autocomplete-python
- atomic-emacs (adds familiar keyboard bindings for emacs users)
- language-ini
- Symbols-list Creates a table on the right side showing all function/method names in the current file
The following themes/ui provide styling similar to the popular Sublime UI:
This screenshot shows the Atom editor window when all of the packages listed above are installed and enabled:
Atom is fairly intuitive, however here are some tutorials:
And just for hahas:
Visual Studio Code (VS Code) is a free, open source multiplatform code editor from Microsoft. Compared to Atom, it tends to be faster, but seems to have a smaller user community. From my initial tests it seems to have more convenient Github integration, excellent support for Typescript/JS development, but configuration is handled by editing JSON files which is efficient, but somewhat lacking usability. VS Code seems to be a good choice for front-end and NodeJS developers. In many regards, Visual Studio Code has a nicer feature set than Atom.
The following extensions are recommended for use with Visual Studio Code and KBase projects. Install them by using ctrl-shift-p/cmd-shift-p to open the command window and entering "extensions: install extensions" or by clicking the extensions icon on the left panel.
- ESLint
- Python - this extension properly works with per project tox.ini files, making Visual Studio Code preferable for Python projects
- Docker
For emacs users, the following extension adds emacs keybindings:
If you would like to use the same editor for Java as well, though this is not yet fully functional for all proejct types:
- https://code.visualstudio.com/docs/languages/java
- Java-Extension-Pack Currently it will work well if you first open a java project in eclipse (and make sure all jars are referenced properly) and then later open it in VScode (it can read the files eclipse creates to understand the classpath)
VS Code has a built in Markdown preview - from any markdown file, pressing ctrl-shift-V ( command-shift-V on Macs) will toggle between markdown source code and a fully rendered markdown preview.
The standard github support in VS Code works well without additional extensions, but if you want even more in editor Git:
Code minimap is a built in feature now.
VS Code has many features built in, these tutorials are a good starting point:
- https://code.visualstudio.com/docs/editor/codebasics
- https://code.visualstudio.com/docs/languages/python
- https://code.visualstudio.com/blogs/2016/02/23/introducing-chrome-debugger-for-vs-code
Configuration in done through Json files, workspace settings will ovveride global settings so if you want different globals than these configurations add them to workspace settings for your project
- For Python you will need to enable Flake8 Support and possibly configure your python path
- If you are editing an app created using the KBase SDK then any modules you install will not be available by default to intellisense so you will need to add the lib directory: "python.autoComplete.extraPaths": ["lib/"]
To open these files use ctrl-shift-p/cmd-shift-p and enter "preferences: open workspace settings" or "preferences: open user settings, you can also click the gear in the bottom left and then click Settings.
an example global Json
{
"terminal.integrated.fontFamily": "Fira Code",
"editor.fontFamily": "'Fira Code'",
"editor.fontSize": 14,
"editor.fontLigatures": true,
"workbench.iconTheme": "vscode-icons",
"python.pythonPath": "python2",
"python.linting.flake8Enabled": true,
"python.linting.pylintEnabled": false
}And workspace for SDK App
{
"python.autoComplete.extraPaths": [
"lib/"
]
}VSCode also comes with an integrated visual debugger, debugging remotely or inside of Docker can take some configuration so there is seperate documentation for doing that