# Day 3: How to write good code comments?

**URL:** <https://sef.discourse.group/t/day-3-how-to-write-good-code-comments/45>\
**Category:** Development\
**Created:** [April 9, 2020, 5:26am UTC](https://sef.discourse.group/t/day-3-how-to-write-good-code-comments/45 "2020-04-09T05:26:13Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![jaye](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/jaye/32/810_2.png) [@jaye](https://sef.discourse.group/u/jaye)\
**Post date:** [April 9, 2020, 5:26am UTC](https://sef.discourse.group/t/day-3-how-to-write-good-code-comments/45/1 "2020-04-09T05:26:13Z")

</div>

![image](https://global.discourse-cdn.com/free1/uploads/sef/original/1X/f98d423082cd5425f4776e402b6ff4f230604a41.jpeg)

Commenting involves placing **Human Readable Descriptions** inside of computer programs detailing what the **Code** is doing. Proper use of commenting can make code maintenance much easier, as well as helping make finding bugs faster. Further, commenting is very important when writing functions that other people will use. Remember, a well-documented code is as important as correctly working code.

Today, the challenge is to share one essential thing to consider when code commenting. You should nominate another one after posting yours.

## Keep them short

Comments are controversial, so the shorter the better:

```auto
// we need this to set up the user's permissions for v3 auth method
# should be
// set user permissions for updated v3 auth

```

I nominate @piumal1999 🤭

---

<div class="post-metadata">

**Author:** ![piumal1999](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/piumal1999/32/274_2.png) [@piumal1999](https://sef.discourse.group/u/piumal1999)\
**Post date:** [April 9, 2020, 1:17pm UTC](https://sef.discourse.group/t/day-3-how-to-write-good-code-comments/45/2 "2020-04-09T13:17:27Z")

</div>

**Don’t make redundant comments**  
A redundant comment is a comment that is not more informative than the code. It does not justify the code or provide intent. These comments only clutter the code.

```
// Method that return true if when stream is open
// Throws an exception if stream is closed
public function waitForStreamClose() {
    if (!$this->closed) {
        return true;
    }
    throw new Exception('Stream still open');}

```

I nominate @anjisvj

---

<div class="post-metadata">

**Author:** ![anjisvj](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/anjisvj/32/9_2.png) [@anjisvj](https://sef.discourse.group/u/anjisvj)\
**Post date:** [April 13, 2020, 7:22am UTC](https://sef.discourse.group/t/day-3-how-to-write-good-code-comments/45/3 "2020-04-13T07:22:38Z")

</div>

**Always start with a capital letter**  
When you are writing a comment always start with a capital letter.

ex:  
✅ correct  
`// This is a comment`

❌ incorrect  
`// this is a comment`

I nominate @Gravewalker😋 to continue.

---

<div class="post-metadata">

**Author:** ![Gravewalker](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/gravewalker/32/12_2.png) [@Gravewalker](https://sef.discourse.group/u/Gravewalker)\
**Post date:** [April 27, 2020, 6:54am UTC](https://sef.discourse.group/t/day-3-how-to-write-good-code-comments/45/4 "2020-04-27T06:54:03Z")

</div>

### Don’t put already available information

Don’t write a story in the comment as your name, employee id, your department, etc because that information can be obtained from Git commit data in case someone wants to know who has made this change.

I nominate @Janeth_Fernando

---

<div class="post-metadata">

**Author:** ![Janeth\_Fernando](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/janeth_fernando/32/740_2.png) [@Janeth\_Fernando](https://sef.discourse.group/u/Janeth_Fernando)\
**Post date:** [April 27, 2020, 7:44am UTC](https://sef.discourse.group/t/day-3-how-to-write-good-code-comments/45/5 "2020-04-27T07:44:06Z")

</div>

**Never denigrate the author**  
In open-source projects, I have seen comments which are written to denigrate the real author. For an example look the following comment.

`//This function looks like it was written by a third-grader.`  
`//It shouldn't work, but it does somehow. I don't want`  
`//to fix it because I want you all to see how bad it is.`

We should never do this. Even if you think you’re being funny or that it makes you look good, it isn’t and it doesn’t.

I nominate:- @Yohan 😁