# Code Readability and Commenting

## Code Readability

### General
- Prettify your code before committing it to git.
- Do not mutate an object or state. Use immutability-helper instead.
- Add proper comments to your code wherever necessary.
- Do not chain more than two operations in one statement. Separate those into separate operations and use them in conjunction. An example of that would be:

**Not/less readable:**

    const data = _.get(getValueList().filter(values, value => value.key), 'node', {});

**Comparatively more readable:**

    const valueList = getValueList().filter(values, value => value.key);
    const data = _.get(valueList, 'node', {});

- Remove unused
- module imports
- css classes
- passed props
- module functions
- Do not commit commented code. Please remove them before committing it to git. An example of that would be:

    // const a = 2;
    // const b = 'abc';

If you want to keep it intentionally then please add a note above it mentioning its reason. Also TODO flag can be used if you are commenting a pending work. But commenting code in any case is not recommended.

- Do not commit **debugger**(s) and **console**(s) with your code. Review your changes carefully before committing it.
- console.error used in catch block are exceptions
- Each and every piece of your code should be lint passed.
- Declare the functions/methods above the code that uses them.
- Group the statements written with same intention together (Law of proximity).
- Deconstruct the props and state to be used on the top in functional scope
- A function must be written with an intention to handle only one task. Try not to acheive more than one thing in a same function.
- Take the help of coercion in evaluating truthness or falsiness. E.g: !!currentScreen
- Early returns promote code readability with negligible performance difference

// Bad:
function returnLate( foo ) {
  var ret;

  if ( foo ) {
    ret = "foo";
  } else {
    ret = "quux";
  }
  return ret;
}

// Good:

function returnEarly( foo ) {

  if ( foo ) {
    return "foo";
  }
  return "quux";
}

- An empty block or block-like construct may be closed immediately after it is opened, with no characters, space, or line break in between (i.e. {}), unless it is a part of a multi-block statement (one that directly contains multiple blocks: if/else or try/catch/finally).
- Example

    function doNothing() {}

- Disallowed

    if (condition) {
      // …
    } else if (otherCondition) {} else {
      // …
    }

    try {
      // …
    } catch (e) {}

- Use object shorthand.
- Example

          const name = "John";
          const age = 18;
          
          const person = {
              name
              age
          };

- Disallowed

          const name = "John";
          const age = 18;
          
          const person = {
              name: name
              age: age
          };

### Naming Conventions
- Dont hesitate to write descriptive variable or function names.
- Be kinder, more thoughtful in naming
- 'student' is storing single student(Object) and 'students' is storing array of students(Objects).
- variable names should be based on what it is storing. 'studentIds' if storing array of student 'ids' and 'students' if storing array of students(Objects).
- Follow camelCase when naming a variable or methods.
- Follow PascalCase when naming components or file names.
- Constants should follow UPPER_SNAKE_CASE.
- In-short:
- functionNamesLikeThis
- variableNamesLikeThis
- ComponentNamesLikeThis
- EnumNamesLikeThis
- ENUM_ITEM_LIKE_THIS
- methodNamesLikeThis
- SYMBOLIC_CONSTANTS_LIKE_THIS
- Camel case: defined
- Don't use abbreviation until its well-known. Examples
- thumbnailUrl (Good)
- thumbUrl(Bad)
- studendId (Good)
- stndId(Bad)
- Few other examples
|Prose form|Correct|Incorrect|
|----------|-------|---------|
|"XML HTTP reuest"|XmlHttpRequest|XMLHTTPRequest|
|"new student ID"|newStudentId|newCustomerID|
|"inner stopwatch"|innerStopwatch|innerStopWatch|
|"supports IPv6 on iOS?"|supportsIpv6OnIos|supportsIPv6OnIOS|
|"YouTube importer"|YouTubeImporter|YoutubeImporter|
|"non-empty"|nonEmpty|nonempty|

## Commenting
### Introduction

> The goal of every programmer should be to write code so clean and expressive that code comments are unnecessary. Well named classes, functions, and variables should guide the reader through your code like a well-written novel.

We all write some code at some point of time based on problem description. And when we face some issue in that particular section, after visiting again, we get troubled at understanding that how this used to work? Were there any hack/exceptions covered? And in these scenarios we lose, unnecessarily, a lot of time which could have been avoided.

So, what’s the solution for this? Yes, you might have guessed right. Writing comments.

Commenting is essential and integral part of writing a clean code. As we all know that how important a cleaner code is. It reduces the issues related to understanding the functionality and state of the piece of code when any developer visits it again. Enforcing this good habit is bit tedious initially but in future it’s very helpful in understanding the right piece of code in very short span.

Based on the scenarios and type of codes, the commenting rules have been defined and needed to be followed strictly to have a common standard practices which can be helpful for peer developers.

Types
* **Documentation comments**: Documentation comments are intended for anyone who is likely to consume the source code, but not likely to read through it.
* Reusable components
* Utilities
* Modules
* **Clarification comments**: Clarification comments are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code. For hacks, exceptions, tricky statements, optimisations, etc .
* Non reusable components
* Reusable components
* Stylesheets
* Utilities
* Modules

Benefits
* Developer gets the idea: what and why(important than what) of functionality before going through the code.
* Reduces the time to understand, hence, easy to debug.
* Code becomes easy to maintain.
* Helpful in identifying hacks or exceptions(if any) in code.
* A well commented code can be a great help for any level of developers, especially junior developers.

Issues
* Need Maintenance

### Rules
The rules are divided by the type of code a developer writes.

Components
Component description

Method description

Clarification comment

Utilities

Hacks

Unused codes
There is a special condition with unused codes. Generally, it’s not preferred to keep the unused codes but if it’s somehow important in future applications just comment the piece and write few comments about it.

### Reference

* For detailed JSDoc documentation please refer to this link: [https://jsdoc.app/about-getting-started.html#:~:text=JSDoc 3 is an API,HTML documentation website for you](https://jsdoc.app/about-getting-started.html#:~:text=JSDoc%203%20is%20an%20API,HTML%20documentation%20website%20for%20you).