Hacker News Reader

Comment by macford | Hacker News Reader

are you working on an open project that involves team? Then IMHO you need comments, but most of the time I develop website and app by myself and I don't need much comment for explaining, only as reference as to what the code section is, and no one has complained about it yet

View on HN

Maybe it's just me, but on several occasions I've gone back to (uncommented) code I'd written several month or years ago, and thought "what the hell is going on here? Who wrote this shit?" Those time I really wish past me had taken a few seconds to write out exactly why he had solved that particular problem in that particular way, despite how obvious it no doubt seemed at the time. There are few things more annoying than finding some 'ugly' code, fixing it, having a bunch of stuff subtly break and then finally remember that there was a very good reason why you originally wrote the code the way you did. If only I'd left a comment of two for future me, much time and anguish could be saved.

Sounds to me like tests could have helped your code far more than any comments would have.

Some stuff, especially stuff connected to performance or memory usage, is very tricky to write tests for. Doubly so if it is only a problem on certain hardware.

That's certainly true. I'd argue though, that most code is in a position where good naming and tests provide sufficient clarity, without requiring free-text comments.

Tests can only tell you what some piece code is supposed to do, not why its doing it the way its doing. Why do you choose to define this particular constant to this particular value, why are you using that particular data structure, why are you rolling your own version of a certain function rather than using the one supplied in the library you are using, why are you using that seemingly round about way to get to that particular result?

There are lots and lots of ways to write a function that passes a test, I want to know if there is a reason why you chose the approach you used.

It really doesn't matter to me whether I am working alone or with a team. Comments, in my world, are an inseparable part of writing code.

As an example, I do both hardware and software. I might work on FPGA code for months and then move on to the embedded code that runs the board. It is possible to not have to touch the FPGA code for months.

If I then have to go and modify something, say, add a register to implement a function I need, comments are a life-saver because you need to do a hard "context switch" in your head. I don't have time to read through code and figure out how a particular chunk-o-code works or what I meant by it. With FPGA code, where you are likely dealing with code structures that are controlling signals in the nanosecond range, you can't wing it. It either works or it doesn't and even minor code changes can make the entire thing go from working to a friggin mess. Comments are the "user manual" to the code.

Later on I might have to go and work on the iOS app that might access this hardware. So now you have FPGA code, embedded code (runs the board that has the FPGA) and iOS code.

Once again, even when I could be the only developer in the project without comments the entire thing becomes unmanageable very, very quickly.

Reply on news.ycombinator.com