No Comment(s)?

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!

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.
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!

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.
/*
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.

Link: https://dev.to/jessicabetts/no-comment-s-pnh