Karim Aya

Karim Aya

1566265027

Document your Javascript code with JSDoc

Introduction

In this post I’ll try to cover everything you need to know to get started with JSDoc. I’ll also share with you some other cool stuff I learned about it that you might find useful.

Table of contents

  • Installation
  • Usage
    DocumentExportExport files or foldersExport all files recursivelyUse a configuration file* Other cool stuff about JSDoc
    Built-in support in VSCodeUse a custom layoutJSDoc and SwaggerKnow any other interesting JSDoc feature?
    JSDoc is an open source API documentation generator for Javascript. It allows developers to document their code through comments. Here’s an example:
/**
 *  Retrieves a single file by id.
 *  @param {string} id File identifier.
 *  @returns {File} File object.
 */
const getFileById = (id) => {
    // ...
}

Once your code is fully documented you can easily generate a website containing all the API documentation by running a simple command. How cool is that?

Here’s how the previous code would look like in the generated website:

Installation

Install JSDoc globally through npm using this command:

npm install -g jsdoc

Or use the following command to install it for a single project:

npm install --save-dev jsdoc

More info on installation here

Now, to be honest, even though I’ve been using JSDoc comments to document my code for a long time, I didn’t install this package until a few weeks ago because I didn’t actually needed to generate the website. Instead I was just using it with VSCode, but I’ll talk about that later in this post.

Usage

Document

To start documenting your code all you have to do is add a comment starting with /** over each block of code you want to document: Modules, methods, classes, functions, etc.

You can keep it simple by just adding a description: “”

/**
 * Retrieves a user by email.
 */
const getByEmail = async (email) => {
    // ...
}

Or you can take full advantage of JSDoc using tags:

/**
 * Retrieves a user by email.
 * @async
 * @method
 * @param {String} email - User email
 * @returns {User} User object
 * @throws {NotFoundError} When the user is not found.
 */
const getByEmail = async (email) => {
    // ...
}

There’s a huge list of tags you can choose from to document your code as thoroughly as you as please.

Remember, the more info you add to your comments, the more detailed your API documentation will be. But also, find the amount of detail that feels right to you. It’s better to have all your code documented with only a few tags than to have only a few methods fully documented using all the tags because it was too much and you couldn’t keep up.

Export

After adding the comments all that’s left to do is generate your documentation website:

Export files or folders

Simply call jsdoc and add the path to the file or folder.

jsdoc path/to/my/file.js

To include many files or folders, add all their paths separated by a single space.

Export all files recursively

jsdoc -r .

Use a configuration file

It’s likely that you’re working on a big project with many files and folders that you want to export, and also some that you need to exclude (I’m looking at you, node_modules). If that’s the case you may want to use a JSDoc Configuration file.

Using a configuration file allows us to customize JSDoc behavior, like:

  • Which folders or files should be included and which excluded.
  • How deep JSDoc will go when we use the --recurse option.
  • Apply customizations to the template
  • etc

All you need to do is create a .json file containing the settings you want and then use the -c or --configure option to tell JSDoc to where they are:

jsdoc -c /path/to/conf.json

Here’s a (very simple) example that I often use:

{
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",   // Only process file ending in .js, .jsdoc or .jsx
        "include": ["."],                       // Check all folders.
        "exclude": ["node_modules"]             // Be gone, node_modules.
    },
    "recurseDepth": 10,                         // Only go 10 levels deep.
    "opts": {
        "destination": "./docs/",               // Where I want my docs to be generated.
        "recurse": true                         // Same as using -r or --recurse
    }
}

Pro tip:> You may want to add the command to your package.json scripts:

"scripts": {
    "generate-docs": "jsdoc -c /path/to/my/conf.js"
}

Then simply use npm run generate-docs from the command-line.

Or you can use sillier names for the script, like: docs-pls, gimme-docs or ill-have-the-large-docs-with-extra-docs (well, maybe not the last one 😅 ).

More info on Configuration here

Other cool stuff about JSDoc

Built in support in VSCode

So, like I said, I was enjoying JSDoc even before installing it, and that’s because VSCode has built-in support for JSDoc annotations, which includes:

A snippet that builds the JSDoc annotation structure for you when you type /** (and then press enter) before a function declaration.

Rich hover information

Info about the function signature as you’re using it

For more info about JSDoc support in VSCode check VSCode docs.

Use a custom layout

You can create your own template for your API documentation by generating a custom layout.tmpl file and setting the option templates.default.layoutFile to the path of your custom layout in your JSDoc configuration file.

Don’t have the time to generate your own template? Here are a few pretty neat template projects you can use:

JSDoc and Swagger

This project swagger-jsdoc integrates JSDoc with swagger allowing you to write the specification for your routes using the tag @swagger over your block code:

  /**
   * @swagger
   * /:
   *   get:
   *     description: "Returns all users."
   *     responses:
   *       200:
   *         description: "All users were returned."
   */
  app.get('/users', (req, res) => {
    // ...
  });

Know any other interesting JSDoc feature?

===========================================

Thanks for reading :heart: If you liked this post, share it with all of your programming buddies! Follow me on Facebook | Twitter

Learn More

Svelte.js - The Complete Guide

The Complete JavaScript Course 2019: Build Real Projects!

Become a JavaScript developer - Learn (React, Node,Angular)

JavaScript: Understanding the Weird Parts

JavaScript: Coding Challenges Bootcamp - 2019

The Complete Node.js Developer Course (3rd Edition)

Angular & NodeJS - The MEAN Stack Guide

NodeJS - The Complete Guide (incl. MVC, REST APIs, GraphQL)

Node.js Absolute Beginners Guide - Learn Node From Scratch

#javascript #web-development

What is GEEK

Buddha Community

Document your Javascript code with JSDoc

Rahul Jangid

1622207074

What is JavaScript - Stackfindover - Blog

Who invented JavaScript, how it works, as we have given information about Programming language in our previous article ( What is PHP ), but today we will talk about what is JavaScript, why JavaScript is used The Answers to all such questions and much other information about JavaScript, you are going to get here today. Hope this information will work for you.

Who invented JavaScript?

JavaScript language was invented by Brendan Eich in 1995. JavaScript is inspired by Java Programming Language. The first name of JavaScript was Mocha which was named by Marc Andreessen, Marc Andreessen is the founder of Netscape and in the same year Mocha was renamed LiveScript, and later in December 1995, it was renamed JavaScript which is still in trend.

What is JavaScript?

JavaScript is a client-side scripting language used with HTML (Hypertext Markup Language). JavaScript is an Interpreted / Oriented language called JS in programming language JavaScript code can be run on any normal web browser. To run the code of JavaScript, we have to enable JavaScript of Web Browser. But some web browsers already have JavaScript enabled.

Today almost all websites are using it as web technology, mind is that there is maximum scope in JavaScript in the coming time, so if you want to become a programmer, then you can be very beneficial to learn JavaScript.

JavaScript Hello World Program

In JavaScript, ‘document.write‘ is used to represent a string on a browser.

<script type="text/javascript">
	document.write("Hello World!");
</script>

How to comment JavaScript code?

  • For single line comment in JavaScript we have to use // (double slashes)
  • For multiple line comments we have to use / * – – * /
<script type="text/javascript">

//single line comment

/* document.write("Hello"); */

</script>

Advantages and Disadvantages of JavaScript

#javascript #javascript code #javascript hello world #what is javascript #who invented javascript

Tyrique  Littel

Tyrique Littel

1604008800

Static Code Analysis: What It Is? How to Use It?

Static code analysis refers to the technique of approximating the runtime behavior of a program. In other words, it is the process of predicting the output of a program without actually executing it.

Lately, however, the term “Static Code Analysis” is more commonly used to refer to one of the applications of this technique rather than the technique itself — program comprehension — understanding the program and detecting issues in it (anything from syntax errors to type mismatches, performance hogs likely bugs, security loopholes, etc.). This is the usage we’d be referring to throughout this post.

“The refinement of techniques for the prompt discovery of error serves as well as any other as a hallmark of what we mean by science.”

  • J. Robert Oppenheimer

Outline

We cover a lot of ground in this post. The aim is to build an understanding of static code analysis and to equip you with the basic theory, and the right tools so that you can write analyzers on your own.

We start our journey with laying down the essential parts of the pipeline which a compiler follows to understand what a piece of code does. We learn where to tap points in this pipeline to plug in our analyzers and extract meaningful information. In the latter half, we get our feet wet, and write four such static analyzers, completely from scratch, in Python.

Note that although the ideas here are discussed in light of Python, static code analyzers across all programming languages are carved out along similar lines. We chose Python because of the availability of an easy to use ast module, and wide adoption of the language itself.

How does it all work?

Before a computer can finally “understand” and execute a piece of code, it goes through a series of complicated transformations:

static analysis workflow

As you can see in the diagram (go ahead, zoom it!), the static analyzers feed on the output of these stages. To be able to better understand the static analysis techniques, let’s look at each of these steps in some more detail:

Scanning

The first thing that a compiler does when trying to understand a piece of code is to break it down into smaller chunks, also known as tokens. Tokens are akin to what words are in a language.

A token might consist of either a single character, like (, or literals (like integers, strings, e.g., 7Bob, etc.), or reserved keywords of that language (e.g, def in Python). Characters which do not contribute towards the semantics of a program, like trailing whitespace, comments, etc. are often discarded by the scanner.

Python provides the tokenize module in its standard library to let you play around with tokens:

Python

1

import io

2

import tokenize

3

4

code = b"color = input('Enter your favourite color: ')"

5

6

for token in tokenize.tokenize(io.BytesIO(code).readline):

7

    print(token)

Python

1

TokenInfo(type=62 (ENCODING),  string='utf-8')

2

TokenInfo(type=1  (NAME),      string='color')

3

TokenInfo(type=54 (OP),        string='=')

4

TokenInfo(type=1  (NAME),      string='input')

5

TokenInfo(type=54 (OP),        string='(')

6

TokenInfo(type=3  (STRING),    string="'Enter your favourite color: '")

7

TokenInfo(type=54 (OP),        string=')')

8

TokenInfo(type=4  (NEWLINE),   string='')

9

TokenInfo(type=0  (ENDMARKER), string='')

(Note that for the sake of readability, I’ve omitted a few columns from the result above — metadata like starting index, ending index, a copy of the line on which a token occurs, etc.)

#code quality #code review #static analysis #static code analysis #code analysis #static analysis tools #code review tips #static code analyzer #static code analysis tool #static analyzer

Giles  Goodwin

Giles Goodwin

1603857900

4 Ways You Can Get Rid of Dirty Side Effects for Cleaner Code in JavaScript

According to an analysis, a developer creates 70 bugs per 1000 lines of code on average. As a result, he spends 75% of his time on debugging. So sad!

Bugs are born in many ways. Creating side effects is one of them.

Some people say side effects are evil, some say they’re not.

I’m in the first group. Side effects should be considered evil. And we should aim for side effects free code.

Here are 4ways you can use to achieve the goal.

1. use strict;

Just add use strict; to the beginning of your files. This special string will turn your code validation on and prevent you from using variables without declaring them first.

#functional-programming #javascript-tips #clean-code #coding #javascript-development #javascript

Samanta  Moore

Samanta Moore

1621137960

Guidelines for Java Code Reviews

Get a jump-start on your next code review session with this list.

Having another pair of eyes scan your code is always useful and helps you spot mistakes before you break production. You need not be an expert to review someone’s code. Some experience with the programming language and a review checklist should help you get started. We’ve put together a list of things you should keep in mind when you’re reviewing Java code. Read on!

1. Follow Java Code Conventions

2. Replace Imperative Code With Lambdas and Streams

3. Beware of the NullPointerException

4. Directly Assigning References From Client Code to a Field

5. Handle Exceptions With Care

#java #code quality #java tutorial #code analysis #code reviews #code review tips #code analysis tools #java tutorial for beginners #java code review

Houston  Sipes

Houston Sipes

1604088000

How to Find the Stinky Parts of Your Code (Part II)

There are more code smells. Let’s keep changing the aromas. We see several symptoms and situations that make us doubt the quality of our development. Let’s look at some possible solutions.

Most of these smells are just hints of something that might be wrong. They are not rigid rules.

This is part II. Part I can be found here.

Code Smell 06 - Too Clever Programmer

The code is difficult to read, there are tricky with names without semantics. Sometimes using language’s accidental complexity.

_Image Source: NeONBRAND on _Unsplash

Problems

  • Readability
  • Maintainability
  • Code Quality
  • Premature Optimization

Solutions

  1. Refactor the code
  2. Use better names

Examples

  • Optimized loops

Exceptions

  • Optimized code for low-level operations.

Sample Code

Wrong

function primeFactors(n){
	  var f = [],  i = 0, d = 2;  

	  for (i = 0; n >= 2; ) {
	     if(n % d == 0){
	       f[i++]=(d); 
	       n /= d;
	    }
	    else{
	      d++;
	    }     
	  }
	  return f;
	}

Right

function primeFactors(numberToFactor){
	  var factors = [], 
	      divisor = 2,
	      remainder = numberToFactor;

	  while(remainder>=2){
	    if(remainder % divisor === 0){
	       factors.push(divisor); 
	       remainder = remainder/ divisor;
	    }
	    else{
	      divisor++;
	    }     
	  }
	  return factors;
	}

Detection

Automatic detection is possible in some languages. Watch some warnings related to complexity, bad names, post increment variables, etc.

#pixel-face #code-smells #clean-code #stinky-code-parts #refactor-legacy-code #refactoring #stinky-code #common-code-smells