TBH, your example on comments shows how not to use comments in most situations. Almost every one of the comments is entirely unnecessary as the code is self-explanatory - as good code should be. Comments should only be used when the code does not lend itself to easy immediate understanding, or when leaving some non-obvious information there would be beneficial to someone coming to the code (maybe a link to an explanation of an algorithm used etc.)
If you were teaching a beginners course on programming your commenting style would be appropriate, but in a setting where the developers working on the code are competent with basic programming concepts, such comments would likely be viewed at best as annoying overkill, or at worst - patronising.
๐ทโโ๏ธ๐๐๐๐ ๐๐/๐๐๐๐ฉ๐ฌ ๐๐ง๐ ๐ข๐ง๐๐๐ซ๐ทโโ๏ธ
โ๏ธI write about AI/ML, Cloud, MLOps, Programmingโ๏ธ
หหหเผบ Giving back to the community through ๐ฆ๐๐๐ฆ๐ป๐ฎ๐ฐ๐ธ.๐ฐ๐ผ๐บ เผปหหห
Location
Australia
Education
๐PhD in Computer Science (Artificial Intelligence )๐
I see your point and honestly I was thinking about this at the time of writing. Just look at it as an example to just get the idea. Not sure what could be a better example. Happy to update it if you have a better example.
It took me a little more than 5 mins to understand moving average and the code. Having these comments would have cut that to less time I feel. Here is my suggestion:
/**
*
* @param arr The input array
* @param windowSize The window size for which moving average needs to be calculated
* @returns Array of moving averages
*/functionmovingAverage(arr,windowSize){letmovingAverages=[];for(leti=0;i<arr.length;i++){// start pointer positioned left by half windowletstart=Max(0,i-Math.floor(windowSize/2));// end pointer positioned right by half windowletend=Min(arr.length,i+Math.ceil(windowSize/2));letsum=0;// calculate sum of subarryfor(letj=start;j<end;j++){sum+=arr[j];}letavg=sum/windowSize;movingAverages.push(avg);}returnmovingAverages;}
Excessive commenting is actually the #1 indicator of unclean code. If your code needs comments to explain it you're probably trying to do too much in one file. To give an example, this comment:
// Calculate the start and end indices for the current window
You should probably just refactor that code into a separate function calculateWindowIndices for example.
Another bad example is redundant comments, like this:
// Loop through the array of numbers
It does not give any more information than what the for loop on the next line already gives. Although there's one problem with that for loop... Its looping over an array called arr that's not a very descriptive name...
The rule of thumb should be: if you feel the need to add a comment to your code, consider refactoring your code to be more self-explanatory.
๐ทโโ๏ธ๐๐๐๐ ๐๐/๐๐๐๐ฉ๐ฌ ๐๐ง๐ ๐ข๐ง๐๐๐ซ๐ทโโ๏ธ
โ๏ธI write about AI/ML, Cloud, MLOps, Programmingโ๏ธ
หหหเผบ Giving back to the community through ๐ฆ๐๐๐ฆ๐ป๐ฎ๐ฐ๐ธ.๐ฐ๐ผ๐บ เผปหหห
Location
Australia
Education
๐PhD in Computer Science (Artificial Intelligence )๐
In my opinion, comments should only be used to clarify non-trivial business logic in your app. For example, I worked on an app for the concrete industry a while back and there was this sieve test logic where you'd have to calculate the modulus of the combined rest weight on all the sieves, but for sand and gravel there were different sieve seizes that we're relevant. That's something that needs additional explaining, although even in that case you can get a long way by writing functions like: getSieveSizesForSand, etc. I think I added a comment with the link to the pdf that had a detailed explanation of how the sieve testing was supposed to work.
In my point of view, youโve missed a lot of topics in efficient and clear JavaScriptโฆ
Some other topics would include:
declaring variables on top of their scope, which makes it easy to see where each variable is in the current scope.
using strict mode.
using let and const instead of var. It helps avoiding a lot of errors and you can have more control over the scope of variables.
using arrow functions as much as possible, except on very specific cases where you can only achieve your goal with a regular function.
And this is only part of a long list of best practices for clean and efficient JavaScript code. It is not only about commenting - which in my opinion, should instead be that the code is self-explanatory, or at least as much as possible -, but also about these aspects and tools that you can make use of in order to make your JavaScript code better to read and function. As for the title of your post, I wouldnโt call it โsuperchargeโ when it comes to skills, this is more about best practices.
๐ทโโ๏ธ๐๐๐๐ ๐๐/๐๐๐๐ฉ๐ฌ ๐๐ง๐ ๐ข๐ง๐๐๐ซ๐ทโโ๏ธ
โ๏ธI write about AI/ML, Cloud, MLOps, Programmingโ๏ธ
หหหเผบ Giving back to the community through ๐ฆ๐๐๐ฆ๐ป๐ฎ๐ฐ๐ธ.๐ฐ๐ผ๐บ เผปหหห
Location
Australia
Education
๐PhD in Computer Science (Artificial Intelligence )๐
๐ทโโ๏ธ๐๐๐๐ ๐๐/๐๐๐๐ฉ๐ฌ ๐๐ง๐ ๐ข๐ง๐๐๐ซ๐ทโโ๏ธ
โ๏ธI write about AI/ML, Cloud, MLOps, Programmingโ๏ธ
หหหเผบ Giving back to the community through ๐ฆ๐๐๐ฆ๐ป๐ฎ๐ฐ๐ธ.๐ฐ๐ผ๐บ เผปหหห
Location
Australia
Education
๐PhD in Computer Science (Artificial Intelligence )๐
That's a valid point, but it's not considering the context. I'm just using that function to somehow show how adding comments in certain blocks can help.
This is perhaps how I'd write it in real life but not sure if it would make more distraction rather than clarity:
/**
* Calculates the moving average of an array of values.
*
* @param {number[]} array - The array of values.
* @param {number} windowSize - The size of the moving average window.
* @return {number[]} The array of moving averages.
*/constmovingAverage=(array,windowSize)=>{if(array.length<windowSize){returnnull;}returnarray.reduce((acc,current,index,array)=>{if(index>=windowSize){acc.push(array.slice(index-windowSize,index).reduce((acc,current)=>acc+current,0)/windowSize);}returnacc;},[]);};
These days the best approach to formatting concerns is to leave that to automated tools like Prettier: you're guaranteed consistent results that avoid unnecessary diffs in your repo.
๐ทโโ๏ธ๐๐๐๐ ๐๐/๐๐๐๐ฉ๐ฌ ๐๐ง๐ ๐ข๐ง๐๐๐ซ๐ทโโ๏ธ
โ๏ธI write about AI/ML, Cloud, MLOps, Programmingโ๏ธ
หหหเผบ Giving back to the community through ๐ฆ๐๐๐ฆ๐ป๐ฎ๐ฐ๐ธ.๐ฐ๐ผ๐บ เผปหหห
Location
Australia
Education
๐PhD in Computer Science (Artificial Intelligence )๐
๐ทโโ๏ธ๐๐๐๐ ๐๐/๐๐๐๐ฉ๐ฌ ๐๐ง๐ ๐ข๐ง๐๐๐ซ๐ทโโ๏ธ
โ๏ธI write about AI/ML, Cloud, MLOps, Programmingโ๏ธ
หหหเผบ Giving back to the community through ๐ฆ๐๐๐ฆ๐ป๐ฎ๐ฐ๐ธ.๐ฐ๐ผ๐บ เผปหหห
Location
Australia
Education
๐PhD in Computer Science (Artificial Intelligence )๐
๐ทโโ๏ธ๐๐๐๐ ๐๐/๐๐๐๐ฉ๐ฌ ๐๐ง๐ ๐ข๐ง๐๐๐ซ๐ทโโ๏ธ
โ๏ธI write about AI/ML, Cloud, MLOps, Programmingโ๏ธ
หหหเผบ Giving back to the community through ๐ฆ๐๐๐ฆ๐ป๐ฎ๐ฐ๐ธ.๐ฐ๐ผ๐บ เผปหหห
Location
Australia
Education
๐PhD in Computer Science (Artificial Intelligence )๐
TBH, your example on comments shows how not to use comments in most situations. Almost every one of the comments is entirely unnecessary as the code is self-explanatory - as good code should be. Comments should only be used when the code does not lend itself to easy immediate understanding, or when leaving some non-obvious information there would be beneficial to someone coming to the code (maybe a link to an explanation of an algorithm used etc.)
If you were teaching a beginners course on programming your commenting style would be appropriate, but in a setting where the developers working on the code are competent with basic programming concepts, such comments would likely be viewed at best as annoying overkill, or at worst - patronising.
I see your point and honestly I was thinking about this at the time of writing. Just look at it as an example to just get the idea. Not sure what could be a better example. Happy to update it if you have a better example.
It took me a little more than 5 mins to understand moving average and the code. Having these comments would have cut that to less time I feel. Here is my suggestion:
I agree. Comments should explain how the logic works if itโs complex, otherwise comments typically describe why.
Excessive commenting is actually the #1 indicator of unclean code. If your code needs comments to explain it you're probably trying to do too much in one file. To give an example, this comment:
You should probably just refactor that code into a separate function
calculateWindowIndicesfor example.Another bad example is redundant comments, like this:
It does not give any more information than what the for loop on the next line already gives. Although there's one problem with that for loop... Its looping over an array called
arrthat's not a very descriptive name...The rule of thumb should be: if you feel the need to add a comment to your code, consider refactoring your code to be more self-explanatory.
I agree with almost every point you made, but I couldn't find a better example. Happy to update the post if you can suggest any.
In my opinion, comments should only be used to clarify non-trivial business logic in your app. For example, I worked on an app for the concrete industry a while back and there was this sieve test logic where you'd have to calculate the modulus of the combined rest weight on all the sieves, but for sand and gravel there were different sieve seizes that we're relevant. That's something that needs additional explaining, although even in that case you can get a long way by writing functions like:
getSieveSizesForSand, etc. I think I added a comment with the link to the pdf that had a detailed explanation of how the sieve testing was supposed to work.In my point of view, youโve missed a lot of topics in efficient and clear JavaScriptโฆ
Some other topics would include:
letandconstinstead ofvar. It helps avoiding a lot of errors and you can have more control over the scope of variables.And this is only part of a long list of best practices for clean and efficient JavaScript code. It is not only about commenting - which in my opinion, should instead be that the code is self-explanatory, or at least as much as possible -, but also about these aspects and tools that you can make use of in order to make your JavaScript code better to read and function. As for the title of your post, I wouldnโt call it โsuperchargeโ when it comes to skills, this is more about best practices.
Thanks for your good addition. Really didn't wan to make the post longer than it is.
That's a valid point, but it's not considering the context. I'm just using that function to somehow show how adding comments in certain blocks can help.
This is perhaps how I'd write it in real life but not sure if it would make more distraction rather than clarity:
These days the best approach to formatting concerns is to leave that to automated tools like Prettier: you're guaranteed consistent results that avoid unnecessary diffs in your repo.
Definitely, it does a massive job in using a proper indentation, not having very long lines and other formatting issues like that.
Information
Thanks, it's a good practice!
I'm glad you find this helpful.
Yup, fair enough.