No Comment(s)?
Tags: commenting, design
Published: 2019-04-23 18:47:21

---
title: No Comment(s)?
published: true
description: Why you should comment your code!
tags: #commenting, #design
---

![no comment](https://media.giphy.com/media/1iuHoo38f5o1n7vvbs/giphy.gif)

I’m just going to get this out of the way… commenting your code is tedious, I know! Many of us developers don’t enjoy it and often times neglect it completely. Short term it sucks. It takes up time and its boring. BUT IT IS SUPER IMPORTANT. I promise commenting is made to help you!!! The purpose of a comment is to make your life easier. I made this blog because I don’t feel that the importance of commenting is stressed enough in education.


##Its all about you!##

![all about me] (https://media.giphy.com/media/7dWcOP3IMbgXLrFm8K/giphy.gif)

READABILITY. READABILITY. READABILITY.

Let’s say you have created a project. 6 months down the road you decide to go back to the code and rewrite it in a new language you have just learned. You are perusing your code, and come across a function you don't understand or do not remember writing. Imagine how much more understandable the code would be if there were some comments explaining what is happening.

```ruby
  def self.valuable?(word) #checks to see if the word should be kept
    valuable = false
    if /[[:upper:]]/.match(word[0]) #if variable
      valuable = true
    elsif word == '"quote_placeholder"' #if string/quote
      valuable = true
    elsif word == '#comment_placeholder' #if comment
      valuable = true
    elsif word == '(param_placeholder' #if params
      valuable = true
    elsif word == 'class_word_placeholder' #if class
      valuable = true
    elsif word.to_i.to_s == word #if num
      valuable = true
    elsif OPERATOR_KEYWORDS.include? word #if operator
      valuable = true
    end
    valuable
  end
```

##It’s not all about you!##

![comes across as selfish](https://media.giphy.com/media/lw40GmL1z9l5f88B2R/giphy.gif)

This concept becomes more important when you are working in a team of developers or  when taking over legacy code. Most people would agree, It is much harder to debug someone else’s code than your own. However, this is what developers do. Sometimes you write new solutions to new problems but often times you will be fixing someone else old code. Because it is easier to understand someone else's code if it has comments, you should do the same. 

###Abstraction###
Commenting will allow people who are unfamiliar with your code to understand more quickly. Rather than reading line by line, one can simply read about its functionality in the comment. This also allows non-programmers to be able to understand your code more clearly. The amount of time it will take to understand the functionality of a method will be greatly increased if the previous developer did not comment their code and do it WELL.

##When should you comment###

It is my opinion that we have a duty to be commenting all code that:
- others will touch/see
- lengthy 
- will be used/looked at in the future
- is not super intuitive
- is not adhering to single responsibility principles
- is not adhering to descriptive naming conventions

Basically always.

##Examples:##

Function name
Input: Type
Output: Type 
Purpose: A brief description of what is accomplished.


```javascript
/*
findStart
input: an array of brewery objects
output: a single brewery object
purpose: finds which brewery you should start with on your brewery crawl
 by:
 - finding the center point of all breweries
 - finding which brewery is farthest from that center point
*/

static findStart(breweries) {
  let coords = Map.getCoords(breweries);
  let center = Map.findCenterPoint(coords)

  let greatest_diff = 0
  let start = null
  breweries.forEach(brewery => {
    let diffLat = Math.abs(center.lat - parseFloat(brewery.latitude))
    let diffLng = Math.abs(center.lng - parseFloat(brewery.longitude))
    let totalDiff = (diffLat * diffLat) + (diffLng * diffLng)
    if (totalDiff > greatest_diff) {
      greatest_diff = totalDiff
      start = brewery
    }
  })
  return start
}
```

Do yourself a favor. Do your fellow coders a favor. Comment your code.