This content originally appeared on DEV Community and was authored by JsRocks
!Comment your code
This code is too complex. I will add a comment to help the next dev.
This is most likely something that every dev has thought of at least once during his career and in most cases has added it.
Why !commenting is important?
JS pun intended, but in case you aren’t aware ! means not
I will start with the obvious.. no matter what programming language you are writing in, its still a programming LANGUAGE. (no the caps were not a mistake)
For example, when you go shopping and you seek assistance from someone, you need to communicate in a language or way that both of you understand to give them context. Why? well how else will that person understand? (don’t say sign language.. its the same principle :P)
Lets try an example where we don’t express ourselves correctly and just use comments to let the other person know what we want.
Say I wanted to find out how much 2 bottles of water cost and the only thing I said was “2 money bottle?” what would the shop assistant understand? Lets use comments like we do when coding to give more context and save the day. ”So what I mean is, how much does 2 bottles of water cost?” Most likely you would get a puzzled face and a comment “why didnt you say so!”
This is the same thing I think when I see something like this
const plwat2 = (wtr=1) => wtr*2. //returns the cost of 2 bottles of water
This comment is necessary cause there is no clue as to what this returns other than the double of wtr. But my initial thoughts are why didnt you say so!
Lets refactor this to promote readability
const costOf2WaterBottles = (waterBottlePrice=1) => waterBottlePrice * 2
…and now lets try and read it again
Cost of 2 water bottles is a function that returns the.. Stop! The function name says it all. Thats your starting point and I know what I am expecting from the function now. Why? Cause I gave good descriptive name to the functions which showed the intention.
Continue though to see how the rest reads through. cost of 2 water bottles is a function that returns the water bottle price * 2
makes sense right? well it would.. we are using words so we have the power of naming and context in our hands when writing code.
Of course this is a fairly simple example but the logic applies to any case even though I am sure somebody may think “try applying this to 50 lines of code and see how it works out…”
My answer would be 50 lines of code is like stating a sentence of 50 lines. Will it make sense?
Comments are the most unmaintainable part of any codebase
Why highly unmaintainable one might say. Well first we must think of our processes in a development cycle to ensure maintenance.
1) developing the actual feature
2) code reviewing
3) testing
4) deploying
During the 4 phases the 2nd is the only one where reviewing it could be done.
How easy can comments be missed or incorrectly reviewed during the review though?
I’d say very easy and the reason is, there is no actual process to safeguard you from incorrect or stale comments.
An important part of our implementation is testing. Not just manually but through unit and automation tests
This is most likely the answer to the question why comments should not be added. How will you test your comments? How will you make sure your comments do not become outdated? More importantly why aren’t you using unit tests? If you are then why do you need comments? Your unit test is the documentation of your piece of code. This is what needs correct descriptions. Why? Cause that is part of a process. However unit testing is a whole other topic which we will get into another time.
The important question when you feel the urge to write a comment is
Can I read this piece of code? If the answer is no, then no-one can. Not even if you after leaving a comment and revisiting it 2 months down the road to refactor something cause you are going to have to read that piece of code line by line and understand what needs to be changed. Even if your code is descriptive you would but the difference being time. How long will it take you to understand both cases?
We have so many tools at our disposal these days that make comments obsolete and unnecessary
linters, type safety features, unit tests, automation tests, code complexity tools, and of course documenting our feature which is !commenting our code
At the end of the day commenting means one or two things
1) Code that isn’t self explanatory because you aren’t giving correct variable, class, function names so things needs to be explained
2) You are doing too many things.
In any case commenting will salvage the moment but not the cause.
When you read code you need to understand it. Having comments negates the purpose of readable code and allows windows of badly written code because “well it was difficult so i have added a comment”. If you can write good comments and bad code then ask someone to help you write in a way that’s readable. Rethink your variable names, functions and logic
Don’t use comments as an excuse to write tens or even hundreds of lines code cause the only thing that you are adding to is complexity to the project. There is no such thing as super duper function, its a mess of an implementation that only at the time of implementing it one can read and nobody else.
Commenting will salvage the moment but not the cause!
In other words the code is complex or non-descriptive!
This content originally appeared on DEV Community and was authored by JsRocks
JsRocks | Sciencx (2022-06-22T10:52:31+00:00) !Comment your code. Retrieved from https://www.scien.cx/2022/06/22/comment-your-code/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.