From 3cc681da6cbb03fb71caf3a7bf4c08b5f70ac429 Mon Sep 17 00:00:00 2001 From: Ewan Cahen Date: Thu, 26 Sep 2024 18:55:52 +0200 Subject: [PATCH 1/2] docs: remove broken link and small improvements --- .github/PULL_REQUEST_TEMPLATE | 2 +- .gitignore | 3 + CITATION.cff | 3 + best_practices/language_guides/javascript.md | 102 ++++++++----------- 4 files changed, 52 insertions(+), 58 deletions(-) create mode 100644 .gitignore diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE index 09e73c01..8e4bed1f 100644 --- a/.github/PULL_REQUEST_TEMPLATE +++ b/.github/PULL_REQUEST_TEMPLATE @@ -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. diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..d303b284 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +# files for JetBrains editors: +**/*.iml +.idea diff --git a/CITATION.cff b/CITATION.cff index a420045d..bc8da5d0 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -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 diff --git a/best_practices/language_guides/javascript.md b/best_practices/language_guides/javascript.md index a973c806..1e25d7b1 100644 --- a/best_practices/language_guides/javascript.md +++ b/best_practices/language_guides/javascript.md @@ -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) # 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/) @@ -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 @@ -66,9 +66,9 @@ 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) @@ -76,25 +76,21 @@ curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash - sudo apt-get install -y nodejs ``` -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. @@ -114,22 +110,22 @@ python3 -m http.server 8000 ``` -Then open the webbrowser to http://localhost:8000. +Then open the web browser to http://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 @@ -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 @@ -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/` package must be installed using npm: +When a library does not ship with type declarations then the libraries `@types/` package must be installed using npm: ```shell npm install --save-dev @types/ @@ -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 -* [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. ## 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. From 82530347739ec82e6946003ccf182dac50d5f698 Mon Sep 17 00:00:00 2001 From: Ewan Cahen Date: Fri, 27 Sep 2024 14:47:48 +0200 Subject: [PATCH 2/2] docs: incorporate suggestions from review --- best_practices/language_guides/javascript.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/best_practices/language_guides/javascript.md b/best_practices/language_guides/javascript.md index 1e25d7b1..f9839b1a 100644 --- a/best_practices/language_guides/javascript.md +++ b/best_practices/language_guides/javascript.md @@ -25,7 +25,7 @@ Another source of information for JavaScript is the MDN Web Docs https://developer.mozilla.org/en-US/docs/Learn -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 @@ -202,15 +202,12 @@ Do not use ``--save`` for types because a production build will have been transp ## Editors and IDEs -These are some good TypeScript editors: - -* [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. ## Debugging In web development, debugging is typically done in the browser. -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