Hacker News Reader

Comment by SamuelAdams | Hacker News Reader

> Documentation lies

This is a very true statement, especially concerning legacy codebases. I have worked on some projects that have had several developers make changes to it.

The original developers were great: they commented every class, had comments for all the methods, and added comments for any complex or funky logic.

Then the changes came. And the next developers hacked and slashed the existing code base to meet the new spec. Except they did not update any of the comments, so now what was once true and reliable is now frail and questionable.

Now, whenever I inherit legacy code riddled with comments, the first thing I do is delete all the comments. This helps me focus on what the code is actually doing, rather than what someone thrice-removed said it should be doing.

View on HN

I was thinking about this and because of the book _Clean Code_ I had already decided that comments will lie at some point.

So I moved towards descriptive variable and function names, but those could lie as well.

So I'm thinking, how could we ensure truthful intentions at all?

And I think only a combination of small pull requests, good variable and function names and a thorough review can save us here.

But I don't know, I'm just a junior developer.

Personally, I think the best thing is education. Now more than ever (in this agile / scrum world) devs are making small, quick changes to existing codebases. These small changes add up, and what was once a great, clean codebase is now riddled with hacks and mis-documented code.

I think educating the developer / team on the existing codebase first would be the right step. Spend a day just going through the code. Learn how it connects, learn the full scope of the project. After this, make your changes in a way that fit into the existing code.

I've had too many offshore developers re-imnplement existing functionality, like reading data from an excel spreadsheet, simply because they did not look through the code that was already there. It cost them 2 hours of work to add another library and implement it, when the code they already needed was a simple using statement away.

In theory, this is why good orgs have senior devs: they know the codebases already. Furthermore, they should be reviewing these changesets to call out devs who mis-document or scatter about the code. But senior devs are people too, and they miss things. Additionally, some codebases are enormously complex, and it's virtually impossible for a single dev to understand it completely.

Types can help. Your code simply won't compile if the types are wrong.

The catch is that you have to define way more types, but if the code is complex enough it's really worth it.

Variable names can also go stale - you should consider replacing all the variable names with placeholders. /s

Deleting all the comments is too far in the extreme. How about just read them and realize they could be stale?

Reply on news.ycombinator.com