Comment by xixixao | Hacker News Reader

Comment by xixixao | Hacker News Reader

Parent Full thread

Here’s a great practice:

1. Write some piece of code

2. Now write a comment about it

3. Is the comment adding more information, making the code more clear?

If Yes: Put that information into the code. Rename variables. Pull out code into subroutines.

If No: Delete the comment.

You’ll be amazed at how often this practice works. Doing it all the time will make your code more readable.

We have a second, enforced practice at work, thanks to code review. The question in your head is simply: “Am I gonna get a comment about this at review time?” If yes, you gotta make the code clearer/simpler/better. Because you’ll have to answer and address the comment, and that’s just gonna slow you down more than if you just fix the problem now.

There are concerns and aspects of software engineering that are important to document but don't sit well in code, but they become important when reading / maintaining that code. Design decisions (implementation details), specification details, other design or engineering constraints. And of course business modeling fundamentals and constraints.

Sure, in theory, you can do everything in code, but I find that usually this trade off is taken, as there's no time/budget to go that 80% extra time. (Or however the Pareto curve looks for the actual problem. And usually it's not less than 80, but more.)

I would never suggest documentation in code alone... Your point is very much noted, echoed and a hat-tip to you here. Yes, documentation is incredibly important, and it should be used as an driver/accompaniment along with comments.

If that works for you then great, but I don't see the value in adding the comment only to remove it one way or another a moment later. What I do is 1. write some code 2. is code clear enough? If yes, stop. 3. clarify the code 4. goto 2.

I agree with you entirely but I can also see that the strategy mentioned could be a good bridge (for those who currently litter code with comments) to a better world where comments are rarely needed.

Reply on news.ycombinator.com