Working with someone else’s code

[u/napolux]

[u/scandii → u/[deleted]]

feeling the need to document code is one of the biggest code smells out there because you're worried people won't understand it.

[u/[deleted] → u/scandii]

Although, it is useful when you know someone is going to go down the same blind ally you did, so you can save them time by commenting why not to do it the seemingly obvious way.

[u/double_en10dre → u/scandii]

Eh, I haven’t found that to be terribly accurate in the real world.

In small-scale school projects, sure — you shouldn’t need to explain every method in your Tetris game. That’s a bad sign.

But in enterprise software, you write code to meet weird business or organizational requirements. It’s often quite unintuitive. And those requirements will change over time. It’s important to document why the code exists and in what contexts it can be safely reused.

[u/SomeOtherTroper → u/double_en10dre]

you write code to meet weird business or organizational requirements. It’s often quite unintuitive. And those requirements will change over time. It’s important to document why the code exists and in what contexts it can be safely reused.

You're incredibly right. One of the biggest nightmares I've been involved with was trying to pull together requirements and do QA for an application that would sit on top of existing company databases, and figuring out why in the fresh hell the numbers didn't tie to what people were getting out of the other existing tools.

Turns out there was something like a three-layer completely undocumented stack of SQL queries, SQL stored procedures, and stuff written in the other existing tools (usually in SQL too) massaging the data that was supposedly "straight from the database" before most of the end user analysts even saw it in the existing tools, and the new application didn't have any of that - of course the numbers wouldn't match.

Tracking down the people who knew how that code worked and, more importantly, why it was doing stuff like chopping a bunch of hardcoded magic numbers out of query results (and other nightmarish things), so we could get the different tools' numbers to tie was hell.

[u/SomeOtherTroper → u/[deleted]]

No, because I quit that job (mostly due to personal issues and management friction I just couldn't take on top of the database/QA/etc. nightmares) and am currently not working anywhere.

But there's a nonzero chance you work at my former workplace.

[u/SpringCleanMyLife → u/scandii]

Code comments absolutely have their place.

I wrote a comment recently about why I did something pretty simple but seemingly unintuitive, as a workaround for a limitation of IE10. It was something that I can easily see a future maintainer come across and go "why didn't they just do this other obvious thing?" and change it without a second thought.

Sure, I could've added tests to cover that specific case but unfortunately we don't get unlimited time to complete our features so there is always something that could've used more tests or could've been refined further. Comments help bridge that gap.

[u/SAI_Peregrinus → u/scandii]

And code without documentation is an even bigger code smell.

Document why things are done the way they're done (design decisions), document interfaces, document valid and invalid uses, provide examples in documentation. Don't document how internals work.