---
title: "Discussion on \"Why you should document your code.\" | Hashnode"
description: "Discussion on \"Why you should document your code.\". Brief History\nA year ago I built an e-commerce API with Flask and consumed it with React on the frontend. It was the first time I built a web app like that where the frontend and backend were very separate because before I would use templating engine..."
url: "https://hashnode.com/posts/why-you-should-document-your-code/5d0f7959f4d779060b593e7f"
---

[Feed](https://hashnode.com/feed) /

Discussion

# [Why you should document your code.](https://hashnode.bywachira.com/why-you-should-document-your-code?utm_source=hashnode&utm_medium=feed)

Brief History A year ago I built an e-commerce API with Flask and consumed it with React on the frontend. It was the first time I built a web app like that where the frontend and backend were very separate because before I would use templating engine...

Jun 23, 2019 · hashnode.bywachira.com  
Read the article

-   [#programming](https://hashnode.com/tag/programming)
-   [#webdev](https://hashnode.com/tag/webdev)
-   [#web-development](https://hashnode.com/tag/web-development)
-   [#programming-cikxvrcrl00bwh453cmkktotz](https://hashnode.com/tag/programming-cikxvrcrl00bwh453cmkktotz)

## Written by

[wachira\_dev](https://hashnode.com/@wwachira)

@wwachira · Worldwide

  
[View profile](https://hashnode.com/@wwachira)

Maker

## Responses 3

Markdown supported · ⌘↵ to post

[Matúš Makatura](https://hashnode.com/@matusmak)

[Jun 25, 2019](https://hashnode.com/posts/why-you-should-document-your-code/5d0f7959f4d779060b593e7f/comment/5d127b55dfeb7b210eb1c077)

From my experience, if your code is well written, you don't have to write **_what_** it does. But always, no matter what, you shall write **_why_** it does it and why not the other way.

Consider the following example snippet. This comment is useless:

```
// Adding fullname property to customers
customers.forEach(_ => _.fullname = `${_.name} ${_.surname}`);
```

Because you can obviously read that from the code. However:

```
// Enriching customers data by caching full name as a property.
// This is later used in both display and some processing to
// reduce boilerplate code
customers.forEach(_ => _.fullname = `${_.name} ${_.surname}`);
```

From this comment, not only you know **_why_** it does it, but also you get a general idea where you would see changes if you decide to remove or modify this code. This is a priceless information if you are working in a large development team.

I found Laravel to be an excellent example of this. For instance, check out this method from SQL [`Query\Builder`](https://github.com/laravel/framework/blob/5.8/src/Illuminate/Database/Query/Builder.php):

```
/**
 * Add a join clause to the query.
 *
 * @param  string  $table
 * @param  \Closure|string  $first
 * @param  string|null  $operator
 * @param  string|null  $second
 * @param  string  $type
 * @param  bool    $where
 * @return $this
 */
public function join($table, $first, $operator = null, $second = null, $type = 'inner', $where = false)
{
    $join = $this->newJoinClause($this, $type, $table);
    // If the first "column" of the join is really a Closure instance the developer
    // is trying to build a join with a complex "on" clause containing more than
    // one condition, so we'll add the join and call a Closure with the query.
    if ($first instanceof Closure) {
        call_user_func($first, $join);
        $this->joins[] = $join;
        $this->addBinding($join->getBindings(), 'join');
    }
    // If the column is simply a string, we can assume the join simply has a basic
    // "on" clause with a single condition. So we will just build the join with
    // this simple join clauses attached to it. There is not a join callback.
    else {
        $method = $where ? 'where' : 'on';
        $this->joins[] = $join->$method($first, $operator, $second);
        $this->addBinding($join->getBindings(), 'join');
    }
    return $this;
}
```

You don't even have to know the bigger picture to understand **_what_** and **_why_** the method and conditions work the way they do. In my opinion, this is what a truly good comments should look like.

[Mark](https://hashnode.com/@mverleg)

[Jun 25, 2019](https://hashnode.com/posts/why-you-should-document-your-code/5d0f7959f4d779060b593e7f/comment/5d11ccde6a72440567a3f5ab)

> Write comments: I definitely changed my mantra from Real Programmers do not comment their code to A quick description won't hurt.

I think that's overcompensating a bit. Having redundant descriptions is useless, and having wrong/outdated descriptions is worse than useless, so technically it can hurt.

You mention someone asking you what the code does. That's a clue that it is not clear enough without comments.

But this is clear enough without the comment, in my opinion:

```
// @route: Gets all profiles
route.get("/profiles", (req, res, next) => {
    // ...
}
```

That said, I like the post and it has good lessons! Use good names, document apis, don't skip comments alltogether.

But just use your judgement on when comments are needed. Don't be extreme in either direction. Try simple code and good names _first_, and _then_ if it's still unclear, add comments.

(As a hint, anything that starts with "real programmers ..." can de [safely](https://en.wikipedia.org/wiki/No_true_Scotsman) disregarded as advice).

[j](https://hashnode.com/@chilimatic)

[Jun 25, 2019](https://hashnode.com/posts/why-you-should-document-your-code/5d0f7959f4d779060b593e7f/comment/5d11ccde6a72440567a3f5ab#reply-5d11cf372509fa0570a25496)

> (As a hint, anything that starts with "real programmers ..." can de safely disregarded as advice).

real programmers would never say such a thing ;D I am more curious what unreal programmers would do or perhaps surreal ones. :D

[david weil](https://hashnode.com/@tenuki)

[Jun 24, 2019](https://hashnode.com/posts/why-you-should-document-your-code/5d0f7959f4d779060b593e7f/comment/5d103a9ed5cbb9062ae50722)

Thanks for your articule! And for the mentioned tools!

[wachira\_dev](https://hashnode.com/@wwachira)

[Jun 24, 2019](https://hashnode.com/posts/why-you-should-document-your-code/5d0f7959f4d779060b593e7f/comment/5d103a9ed5cbb9062ae50722#reply-5d108a68ebdd418f58aa940d)

My pleasure

[Ichoku Chinonso](https://hashnode.com/@ichokuchinonso)

[Jun 26, 2019](https://hashnode.com/posts/why-you-should-document-your-code/5d0f7959f4d779060b593e7f/comment/5d103a9ed5cbb9062ae50722#reply-5d13c7d2f56e74404a412aac)

Thank you very much for this. I gained alot from completing the read.
