undefined | Better HN

0 pointskatbyte13y ago0 comments

his 1st point was not about commenting what code does but why it is done the way it is. I don't see how you can extract all the required information (including web links or rational) explain the rational behind a implementation into a function name.

    // unroll loop for 50% speed increase. Optimal offset 4
    // 3: 25%
    // 4: 50%
    // 5: 40%  
    for(i=0;i<x;i+=4) {
    ...
    }

How could you extract that into a function name?

2 is definitely more an opinion, but I use XML comments on every function, object, parameter, return value with a quick summery because it integrates into my IDE and is used to generate API and library documentation that is invaluable to developers who don't necessary have the code, only the documentation.

0 comments

kamjam13y ago

I use XML comments on every function

I'm not talking about your opinion on point 2 here specifically, but your comment reminded me of a discussion I had with someone about comments... well, they were arguing (like the OP) that you should not use comments in your code but they would gladly use XML comments for the same reasons you have stated. So they would go to the lengths of helping out external developers with comments but not their own internal developers. Seemed very strange to me!

kondro13y ago

I agree, performance optimisations like this definitely require significant documentation.

However, for what most of us do, these optimisations should be rare. More emphasis should be placed on code maintainability than performance of individual components in most situations. Hardware is cheap, developer time is expensive.

j / k navigate · click thread line to collapse