Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove broken link and small improvements #343

Merged
merged 2 commits into from
Sep 27, 2024
Merged

Remove broken link and small improvements #343

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3cc681d
docs: remove broken link and small improvements
ewan-escience Sep 26, 2024
8253034
docs: incorporate suggestions from review
ewan-escience Sep 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,5 +18,5 @@ Feel free to remove what is not applicable.

## ALL contributions
- [ ] I previewed my changes locally using e.g. `python3 -m http.server 4000` and confirmed they work correctly.
- [ ] I checked for broken links, e.g. using the link checker GitHub Action workflow, or locally by using `docker run --init -it -v `pwd`:/docs lycheeverse/lychee /docs --config=docs/lychee.toml`, at least for the files I changed.
- [ ] I checked for broken links, e.g. using the link checker GitHub Action workflow, or locally by using ``docker run --init -it -v `pwd`:/docs lycheeverse/lychee /docs --config=docs/lychee.toml``, at least for the files I changed.
- [ ] My name was added to the `CITATION.cff` file.
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# files for JetBrains editors:
**/*.iml
.idea
3 changes: 3 additions & 0 deletions CITATION.cff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,3 +116,6 @@ authors:
name-particle: van
given-names: Sander
orcid: "https://orcid.org/0000-0001-6159-041X"
- affiliation: "Netherlands eScience Center"
family-names: Cahen
given-names: Ewan
102 changes: 45 additions & 57 deletions best_practices/language_guides/javascript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,35 @@
# Getting started

*Page maintainer: Jurriaan Spaaks* [@jspaaks](https://github.com/jspaaks)
*Page maintainer: Ewan Cahen* [@ewan-escience](https://github.com/ewan-escience)


To learn about JavaScript, view the presentations by [Douglas Crockford](http://en.wikipedia.org/wiki/Douglas_crockford):
To learn about JavaScript, view the presentations by [Douglas Crockford](https://en.wikipedia.org/wiki/Douglas_Crockford):

* [Crockford on JavaScript](http://www.youtube.com/playlist?list=PL7664379246A246CB)
* [JavaScript: The Good Parts](http://www.youtube.com/watch?v=hQVTIJBZook)
* [Crockford on JavaScript](https://www.youtube.com/playlist?list=PL7664379246A246CB)
* [JavaScript: The Good Parts](https://www.youtube.com/watch?v=hQVTIJBZook)
* JavaScript trilogy:
* [The JavaScript Programming Language](http://www.youtube.com/watch?v=v2ifWcnQs6M) (1h50m)
* [Theory of the DOM](http://www.youtube.com/watch?v=Y2Y0U-2qJMs) (1h18m)
* [Advanced JavaScript](http://www.youtube.com/watch?v=DwYPG6vreJg) (1h07m)
* [The JavaScript Programming Language](https://www.youtube.com/watch?v=v2ifWcnQs6M) (1h50m)
* [Theory of the DOM](https://www.youtube.com/watch?v=Y2Y0U-2qJMs) (1h18m)
* [Advanced JavaScript](https://www.youtube.com/watch?v=DwYPG6vreJg) (1h07m)

In [this video](http://www.youtube.com/watch?v=c-kav7Tf834) (47m04s), Nicholas Zakas talks about sustainability aspects, such as how to write maintainable JavaScript, how to do JavaScript testing, and good programming style (much needed in JavaScript).
In [this video](https://www.youtube.com/watch?v=c-kav7Tf834) (47m04s), Nicholas Zakas talks about sustainability aspects, such as how to write maintainable JavaScript, how to do JavaScript testing, and good programming style (much needed in JavaScript).
Among others, he mentions the following style guides:

* [Google's style guide for JavaScript](https://google.github.io/styleguide/javascriptguide.xml);
* [Crockford's style guide](http://javascript.crockford.com/code.html) integrates with [JSLint](http://www.jslint.com/), which in turn is available as a plugin for Eclipse.
* [Crockford's style guide](https://www.crockford.com/code.html) integrates with [JSLint](https://www.jslint.com/), which in turn is available as a plugin for Eclipse.
* Zakas has also written [an excellent book](https://www.oreilly.com/library/view/maintainable-javascript/9781449328092/) on writing maintainable JavaScript, also within the context of working in teams. The appendix contains a style guide with explanation.

[These](http://www.youtube.com/watch?v=yQaAGmHNn9s&list=PLA56F6A06883A2AD8) video tutorials (totaling a couple of hours) are useful if you're just starting with learning the JavaScript language.
[These](https://www.youtube.com/playlist?list=PLA56F6A06883A2AD8) video tutorials (totaling a couple of hours) are useful if you're just starting with learning the JavaScript language.

Another source of information for javascript, is the "web standards curriculum" made by the Web Education Community Group as part of W3C:
Another source of information for JavaScript is the MDN Web Docs

http://www.w3.org/community/webed/wiki/Main_Page
https://developer.mozilla.org/en-US/docs/Learn

In particular, see the page about [Javascript best practices](http://www.w3.org/community/webed/wiki/JavaScript_best_practices)
Additionally, see the page about [JavaScript best practices](https://www.w3schools.com/js/js_best_practices.asp)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Additionally, see the page about [JavaScript best practices](https://www.w3schools.com/js/js_best_practices.asp)
Additionally, see the W3Schools page about [JavaScript best practices](https://www.w3schools.com/js/js_best_practices.asp)


# Frameworks

To develop a web application it is no longer enough to sprinkle some [JQuery](https://jquery.com/) calls on a html page, a JavaScript based front end web application framework must be used. The are very many frameworks, popularity is a good way to pick one.
To develop a web application it is no longer enough to sprinkle some [JQuery](https://jquery.com/) calls on a HTML page, a JavaScript based front end web application framework must be used. There are very many frameworks, popularity is a good way to pick one.
Currently the most popular frameworks are

* [Angular](https://angular.io/)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is Angular still used (by us or others in research)?

Should we also add Svelte or other SSR frameworks?

Can also do this in a follow-up PR, but just wondering.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was planning to have a look at frameworks in a future branch.

Expand All @@ -47,13 +47,13 @@ To create a Angular application use [Angular CLI](https://cli.angular.io/).
## React

[React](https://facebook.github.io/react/) is a library which can used to create interactive User Interfaces by combining components. It is developed by Facebook.
Where Angular and Vue.js are frameworks, including all the rendering, routing, state management functonality inside them. React only does rendering so other libraries must be used for routing and state management.
[Redux](http://redux.js.org/) can be used to let state changes flow through React components. [React Router](https://reacttraining.com/react-router/) can be used to navigate the application using URLs.
Where Angular and Vue.js are frameworks, including all the rendering, routing, state management functionality inside them. React only does rendering, so other libraries must be used for routing and state management.
[Redux](https://redux.js.org/) can be used to let state changes flow through React components. [React Router](https://reactrouter.com/) can be used to navigate the application using URLs.

To create a React application use the [Create React App](https://github.com/facebookincubator/create-react-app)
How to develop the bootstrapped app further is described in the README.md.

[TypeScript React Starter](https://github.com/Microsoft/TypeScript-React-Starter#typescript-react-starter) is a Typescript version of create react app.
[TypeScript React Starter](https://github.com/Microsoft/TypeScript-React-Starter#typescript-react-starter) is a TypeScript version of create react app.

## Vue.js

Expand All @@ -66,35 +66,31 @@ To create a Vue.js application use [Vue CLI](https://cli.vuejs.org/).
# JavaScript outside browser

Most JavaScript is run in web browsers, but
JavaScript can also be run on outside browsers with [NodeJS](https://nodejs.org).
JavaScript can also be run on outside browsers with [Node.js](https://nodejs.org).

On Ubuntu (18.04) based systems, you can use the following commands to install NodeJS:
On Ubuntu (18.04) based systems, you can use the following commands to install Node.js:

```shell
# system packages (Ubuntu/Debian)
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt-get install -y nodejs
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this still work after 6 years? That would be amazing!

Could also be updated in another PR, of course.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't test this, wanted to look at this in a future branch.

```

NodeJS comes with a package manager called [npm](https://www.npmjs.com/).
Node.js comes with a package manager called [npm](https://www.npmjs.com/).
The package manager uses https://www.npmjs.com/ as the package repository.

# Editors and IDEs

These are some good JavaScript editors:

* [Atom](http://atom.io) by GitHub
* [Brackets](http://brackets.io/) by Adobe
* [WebStorm](https://www.jetbrains.com/webstorm/) by JetBeans
* [WebStorm](https://www.jetbrains.com/webstorm/) by JetBrains
* [Visual Studio Code](https://code.visualstudio.com) by Microsoft

The best JavaScript editors are currently WebStorm and Visual Studio Code. Atom can have some performance problems, especially with larger files.

# Debugging

In web development, debugging is typically done in the browser.

* The best debugging tool suite is currently the debugger built into the Google Chrome webbrowser, and its open-source counterpart, Chromium. It can watch variables, step through the code, lets you monitor network traffic, and much more. Activate the debugger through the F12 key.
* The best debugging tool suite is currently the debugger built into the Google Chrome web browser, and its open-source counterpart, Chromium. It can watch variables, step through the code, lets you monitor network traffic, and much more. Activate the debugger through the F12 key.
* On Firefox, use either the built-in debugging functionality (again accessible through the F12 button) or install the [Firefox Developer Tools](https://developer.mozilla.org/en-US/docs/Tools).
* Microsoft has a debugging toolset called 'F12' for their Internet Explorer and Edge browsers. It offers similar capability as that of Google Chrome, Chromium, and Firefox.
* In Safari on OS X, press ⌘⌥U.
Expand All @@ -114,22 +110,22 @@ python3 -m http.server 8000
```

<!-- the &#104; notation below is to avoid problems with the link checker (broken-link-checker) -->
Then open the webbrowser to &#104;ttp://localhost:8000.
Then open the web browser to &#104;ttp://localhost:8000.

# Documentation

[JSDoc](http://usejsdoc.org/) works similarly to JavaDoc, in that it parses your JavaScript files and automatically generates HTML documentation. The [Tag Dictionary](http://usejsdoc.org/#JSDoc3_Tag_Dictionary) is an overview of the tag names you can use to document your code.
[JSDoc](https://jsdoc.app/) works similarly to JavaDoc, in that it parses your JavaScript files and automatically generates HTML documentation.

# Testing

* [Jasmine](http://jasmine.github.io/), a behavior-driven development framework for testing JavaScript code.
* [Karma](http://karma-runner.github.io/), Test runner, runs tests in web browser with code coverage. Use [PhantomJS](http://phantomjs.org/) as headless webbrowser on CI-servers.
* [Jasmine](https://jasmine.github.io/), a behavior-driven development framework for testing JavaScript code.
* [Karma](https://karma-runner.github.io/latest/index.html), Test runner, runs tests in web browser with code coverage. Use [PhantomJS](https://phantomjs.org/) as headless web browser on CI-servers.
* [Tape](https://github.com/substack/tape), a minimal testing framework that helps remove some of the black-box approach of some of the other frameworks.
* [Jest](https://github.com/facebook/jest), a test framework from Facebook which is integrated into the [Create React App](https://github.com/NLeSC/create-react-app)

## Web based tests

To interact with web-browsers use [Selenium](http://docs.seleniumhq.org/).
To interact with web-browsers use [Selenium](https://www.selenium.dev/).

Test with
* Local web browser
Expand All @@ -143,33 +139,31 @@ Use a linter like [eslint](https://eslint.org/) to detect errors and potential p

# Showing code examples

Code examples can be stored in Gists in GitHub. [bl.ocks.org](http://bl.ocks.org) allows you to view the resulting page, and serve as a small demo.
There's also [jsfiddle](https://jsfiddle.net/), which shows you a live preview of your web page while you fiddle with the underlying HTML, JavaScript and CSS code.
You can use [jsfiddle](https://jsfiddle.net/), which shows you a live preview of your web page while you fiddle with the underlying HTML, JavaScript and CSS code.

# Code quality analysis tools and services

* [Code climate](https://codeclimate.com) can analyze Javascript (and Ruby, PHP). For example project see https://codeclimate.com/github/NLeSC/PattyVis
* [Code climate](https://codeclimate.com) can analyze JavaScript (and Ruby, PHP). For example project see https://codeclimate.com/github/NLeSC/PattyVis
* [Codacy](https://www.codacy.com) can analyze [many different languages](https://docs.codacy.com/getting-started/supported-languages-and-tools/) using open source tools.
* [SonarCloud](https://sonarcloud.io) is an open platform to manage code quality which can also show code coverage and count test results over time.
Can analyze Java (best supported), C, C++, Python, Javascript and Typescript. For example project see https://sonarcloud.io/dashboard?id=e3dchem%3Amolviewer
Can analyze Java (best supported), C, C++, Python, JavaScript and TypeScript. For example project see https://sonarcloud.io/dashboard?id=e3dchem%3Amolviewer

# TypeScript

http://www.typescriptlang.org
https://www.typescriptlang.org/

Typescript is a typed superset of JavaScript which compiles to plain JavaScript. Typescript adds static typing to JavaScript, which makes it easier to scale up in people and lines of code.
TypeScript is a typed superset of JavaScript which compiles to plain JavaScript. TypeScript adds static typing to JavaScript, which makes it easier to scale up in people and lines of code.

At the Netherlands eScience Center we prefer TypeScript over JavaScript as it will lead to more sustainable software.
At the Netherlands eScience Center we prefer TypeScript to JavaScript as it will lead to more sustainable software.

## Getting Started

To learn about TypeScript the following resources are available:
To learn about TypeScript, the following resources are available:

* [youtube](http://www.youtube.com/playlist?list=PLyJiOytEPs4d9QUQHHSuY3n3nBmkBuqro): tutorials playlist about TypeScript
* [tutorial](http://www.typescriptlang.org/Tutorial) from Microsoft's TypeScript website
* [blog post](http://www.aaron-powell.com/posts/2012-10-03-typescript-source-maps) about how TypeScript can be used with the Google Chrome/Chromium debuggers (and [presumably](https://blog.oio.de/2014/04/04/internet-explorer-11-source-map-based-debugging/) Firefox, and Internet Explorer) through the use of so-called 'source maps'. (Follow [this](http://www.codeproject.com/Articles/649271/How-to-Enable-Source-Maps-in-Firefox) link to set up source mapping for Firefox, also useful for debugging minified JavaScript code).
* [blog post](http://www.sitepen.com/blog/2013/12/31/definitive-guide-to-typescript/) that supposedly is the definitive guide to TypeScript
* [TypeScript Language Specification](https://github.com/microsoft/TypeScript/tree/main/doc)
* Official [TypeScript documentation](https://www.typescriptlang.org/docs/) and [tutorial](https://www.typescriptlang.org/docs/handbook/intro.html)
* [Single video tutorial](https://www.youtube.com/watch?v=d56mG7DezGs) and [playlist tutorial](https://www.youtube.com/playlist?list=PL4cUxeGkcC9gUgr39Q_yD6v-bSyMwKPUI)
* Tutorials on debugging TypeScript in [Chrome](https://blog.logrocket.com/how-to-debug-typescript-chrome/) and [Firefox](https://hacks.mozilla.org/2019/09/debugging-typescript-in-firefox-devtools/). If you are using a framework, consult the documentation of that framework for additional ways of debugging
* [The Definitive TypeScript 5.0 Guide](https://www.sitepen.com/blog/update-the-definitive-typescript-guide)

## Quickstart

Expand All @@ -184,7 +178,7 @@ npm install -g typescript
In TypeScript, variables are typed and these types are checked.
This implies that when using libraries, the types of these libraries need to be installed.
More and more libraries ship with type declarations in them so they can be used directly. These libraries will have a "typings" key in their package.json.
When a library does not ship with type declarations then the libriaries `@types/<library-name>` package must be installed using npm:
When a library does not ship with type declarations then the libraries `@types/<library-name>` package must be installed using npm:

```shell
npm install --save-dev @types/<library-name>
Expand All @@ -196,40 +190,34 @@ npm install react --save
```

To be able to use its functionality in TypeScript we need to install the typings.
We can search for the correct package at http://microsoft.github.io/TypeSearch/ .

And install it with:
Install it with:

```shell
npm install --save-dev @types/react
```

The ``--save-dev`` flag saves this installation to the package.json file as a development dependency.
Do not use ``--save`` for types because a production build will have been transpiled to Javascript and has no use for Typescript types.
Do not use ``--save`` for types because a production build will have been transpiled to JavaScript and has no use for TypeScript types.

## Editors and IDEs

These are some good TypeScript editors:

* [Atom](http://atom.io) by GitHub, with the ``atom-typescript`` Atom package.
* [Brackets](http://brackets.io/?lang=en) by Adobe
* [WebStorm](https://www.jetbrains.com/webstorm/) by JetBrains
* [Visual Studio Code](https://code.visualstudio.com) by Microsoft
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The repetition here feels a bit silly. Suggestion:

Suggested change
These are some good TypeScript editors:
* [Atom](http://atom.io) by GitHub, with the ``atom-typescript`` Atom package.
* [Brackets](http://brackets.io/?lang=en) by Adobe
* [WebStorm](https://www.jetbrains.com/webstorm/) by JetBrains
* [Visual Studio Code](https://code.visualstudio.com) by Microsoft
For editing TypeScript, we recommend the same editors as for JavaScript.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably best to not commit that suggestion, GitHub was warning me that there's some weirdness going on in selecting these lines in the review window.

* [WebStorm](https://www.jetbrains.com/webstorm/) by JetBeans

The best TypeScript editors is currently Visual Studio Code as Microsoft develops both the editor and Typescript.

## Debugging

In web development, debugging is typically done in the browser.
Typescript can not be run directly in web browser so it must be transpiled to Javascript. To map a breakpoint in the browser to a line in the original Typescript file [source maps](https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) are required. Most frameworks have a project build system which generate source maps.
TypeScript cannot be run directly in web browser so it must be transpiled to JavaScript. To map a breakpoint in the browser to a line in the original TypeScript file [source maps](https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) are required. Most frameworks have a project build system which generate source maps.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TypeScript cannot be run directly in web browser so it must be transpiled to JavaScript. To map a breakpoint in the browser to a line in the original TypeScript file [source maps](https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) are required. Most frameworks have a project build system which generate source maps.
TypeScript cannot be run directly in the web browser so it must be transpiled to JavaScript. To map a breakpoint in the browser to a line in the original TypeScript file [source maps](https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) are required. Most frameworks have a project build system which generate source maps.


## Documentation

It seems that [TypeDoc](http://typedoc.io/) is a good tool to use.
Alternative could be [TSdoc](https://www.npmjs.com/package/tsdoc)
It seems that [TypeDoc](https://typedoc.org/) is a good tool to use.

## Style Guides

[TSLint](https://github.com/palantir/tslint) is a good tool to check your codestyle.
[TSLint](https://github.com/palantir/tslint) is a good tool to check your code style.

For the [sim-city-cs project](https://github.com/indodutch/sim-city-cs/) we use [this](https://github.com/ReGIS-org/regis/blob/develop/tslint.json) tslint.json file.
Loading