Trouble maker and Problem solver ⚙️🔧
Loves simplicity, hates bullshit 💩.
Productivity obsessed, avid learner 🖥🚀
Sport and outdoor freak 🧗⛰
Metalhead 🎸🤘 Father of 2 👨👩👦👦
Opinions are my own
first answer: nowhere. code should be readable and understandable without having to explain it in english ( which often ends up even more verbose and confusing, and most of the time outdated)
second answer: above. if you need to explain WHY some code does something ( and not WHAT) place it before, that means, the line above. you read the code from top to bottom, so first thing you read the comment that introduces/explain what is following.
Trouble maker and Problem solver ⚙️🔧
Loves simplicity, hates bullshit 💩.
Productivity obsessed, avid learner 🖥🚀
Sport and outdoor freak 🧗⛰
Metalhead 🎸🤘 Father of 2 👨👩👦👦
Opinions are my own
the WHY is mostly some business logic rule or requirement, or something that by thinking about the feature/functionality is cumbersome or counterintuitive. ( or maybe you want to point out some very hidden internals of a native or 3rd party method ).
const add = (a, b) => a + b
here a comment is absolutely useless, what value would a comment like receives 2 numbers as parameters and returns one number which is the sum of the 2 add?
if on the other hand you have a method that sums number but should never return an odd number and therefore appends 1 to make the result even ( dont ask me why you would have such a method, just made that up), a comment might make sense indeed.
const noOddsAdd = (a,b) => {
let sum = a+b
// our legacy system can't accept odd numbers
// therefore whenever we do a sum operation we need to return an even number
// and add 1 to any odd result;
return sum%2 !=0 ? ++sum : sum
}
Trouble maker and Problem solver ⚙️🔧
Loves simplicity, hates bullshit 💩.
Productivity obsessed, avid learner 🖥🚀
Sport and outdoor freak 🧗⛰
Metalhead 🎸🤘 Father of 2 👨👩👦👦
Opinions are my own
another reason why comments should be minimal, even to explain the WHY above is that we should have Unit Tests! Unit Tests are uptodate documentation of the edge cases and weird behaviours of a method.
test("when sum would be odd, method returns an even number anyway", ()=>{
const result = noOddsAdd(4,5);
expect(result).toBe(10)
))
I prefer minimal comments too - you have to maintain them as well as the code.
I don't know what is worse for a complex piece of code - no comments or comments that no longer reflect what is going on - as you said, it can lead to more confusion and send you down a rabbit hole.
French software engineer with 15 year experience on 3D data visualisation and processing. Lots of C++, and switch to Unity recently.
I like when it run fast 😉
I wouldn't be so categorical. The auto-documented code may be possible with high level language like Python or Ruby, and simple business logic. But when dealing with low level kernel code in C, C++ or scientific algorithm, even in Python, I dare you to understand it without comment.
Could-you explain me what does this code ? 😁
// Compute an approximation of 1/sqrt(number)floatQ_rsqrt(floatnumber){longi;floatx2,y;constfloatthreehalfs=1.5F;x2=number*0.5F;y=number;i=*(long*)&y;i=0x5f3759df-(i>>1);y=*(float*)&i;y=y*(threehalfs-(x2*y*y));}
first answer: nowhere. code should be readable and understandable without having to explain it in english ( which often ends up even more verbose and confusing, and most of the time outdated)
second answer: above. if you need to explain WHY some code does something ( and not WHAT) place it before, that means, the line above. you read the code from top to bottom, so first thing you read the comment that introduces/explain what is following.
Oh okay-
Everybody says this without examples.
Could you give an example of a comment that explains the why?
the WHY is mostly some business logic rule or requirement, or something that by thinking about the feature/functionality is cumbersome or counterintuitive. ( or maybe you want to point out some very hidden internals of a native or 3rd party method ).
here a comment is absolutely useless, what value would a comment like
receives 2 numbers as parameters and returns one number which is the sum of the 2
add?if on the other hand you have a method that sums number but should never return an odd number and therefore appends 1 to make the result even ( dont ask me why you would have such a method, just made that up), a comment might make sense indeed.
another reason why comments should be minimal, even to explain the WHY above is that we should have Unit Tests! Unit Tests are uptodate documentation of the edge cases and weird behaviours of a method.
I prefer minimal comments too - you have to maintain them as well as the code.
I don't know what is worse for a complex piece of code - no comments or comments that no longer reflect what is going on - as you said, it can lead to more confusion and send you down a rabbit hole.
Ah okay
I wouldn't be so categorical. The auto-documented code may be possible with high level language like Python or Ruby, and simple business logic. But when dealing with low level kernel code in C, C++ or scientific algorithm, even in Python, I dare you to understand it without comment.
Could-you explain me what does this code ? 😁
For the answer: en.wikipedia.org/wiki/Fast_inverse...
Oh okay