DEV Community

Discussion on: Commenting: where?

View post
Collapse
 
dvddpl profile image
Davide de Paolis •

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.

Collapse
 
vulcanwm profile image
Medea •

Oh okay-

Collapse
 
kelvinokuroemi profile image
KelvinOkuroemi •

Everybody says this without examples.
Could you give an example of a comment that explains the why?

Collapse
 
dvddpl profile image
Davide de Paolis • • Edited

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
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode
Thread Thread
 
dvddpl profile image
Davide de Paolis •

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)
))
Enter fullscreen mode Exit fullscreen mode
Collapse
 
myleftshoe profile image
myleftshoe •

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.

Collapse
 
vulcanwm profile image
Medea •

Ah okay

Collapse
 
tandrieu profile image
Thibaut Andrieu •

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)
float Q_rsqrt( float number )
{
    long i;
    float x2, y;
    const float threehalfs = 1.5F;

    x2 = number * 0.5F;
    y  = number;
    i  = * ( long * ) &y;
    i  = 0x5f3759df - ( i >> 1 );
    y  = * ( float * ) &i;
    y  = y * ( threehalfs - ( x2 * y * y ) );
}
Enter fullscreen mode Exit fullscreen mode

For the answer: en.wikipedia.org/wiki/Fast_inverse...

Collapse
 
vulcanwm profile image
Medea •

Oh okay