Ask HN: What's your secret weapon for keeping code/docs/tests from rotting?

3 pointsbochoh7mo ago4 comments

I've been using cursor lately to handle some (most) of the grunt work and it's been surprisingly useful for two things: keeping documentation from going stale and spotting gaps in test coverage. For example, I'll ask it things like "what's the most likely way this function could break?" and it will suggest edge cases I hadn't thought of.

That said, it's not (maybe?) magic and sometimes hallucinates test cases that are rubbish so some critical thinking is still required.

I'm curious what y'all are using to keep docs/tests maintainable? Are you leaning on AI or doing it the old fashioned way?

4 comments

sunscream897mo ago

You make the most junior member of your team take notes or revise them as they are directed to deal with each issue (like final step in closing the ticket.)

I know, I know, “everyone should do it.” Everyone is not going to do it, everyone left it undone the last times.

Works best when someone is trying to impress, or is told to do it in some essential capacity.

And there is also the setting of a good example.

speedgoose7mo ago

I don’t write documentation about code. I do for the architecture and the APIs, but the code is self documented.

moomoo117mo ago

If you follow basic things like single responsibility principle and layers you don’t need code documentation.

The tests can be a useful guide on how the code is supposed to work. But let’s be honest most test suites become wack any time you work on really big or complex projects.

I think the best thing you can do is optimize for that. Write code in a clean way, and organize tests in a way that can quickly convey high level functionality to maintainers.

If you find yourself writing tests that are doing too much or need to add documentation to code, you’re probably doing other things wrong too. (Not you btw just saying in general)

AnimalMuppet7mo ago

> If you follow basic things like single responsibility principle and layers you don’t need code documentation.

Yes, write the code so cleanly, and with such good names, that you don't need documentation. Absolutely.

But the code is never quite clean enough, and the names are never clear enough, and the people coming later don't know everything that you know. So write documentation anyway. And not just "sling something out there" - write the best documentation you can; write it as well as you write the code.

(No, I don't do as I say. But it's the right thing to do...)

j / k navigate · click thread line to collapse