Skip to content
loading...

re: What makes maintaining documentation difficult? VIEW POST

FULL DISCUSSION
 

Maintaining code and documentation separately makes it painful. Also, I'm just bad at documenting things. 😶

 

Code can't lie, documentation can. It's sooo easy to get them out of sync.

 

I like how modern languages acknowledge this problem by trying to solve it in the language itself.

Both go & rust address this by encouraging you to add documentation along with your code and include nice tooling to generate documentation from comments in your code.

After adopting Go as my primary back-end language, I found myself applying some of those good habits in other languages I use.

 

code tells exactly what it does. sometimes it's not what you expect, though

Only when working solely with primitive operators that cannot be overloaded. Otherwise, code can easily lie. There is no shortage of methods like getFoo(), that only retrieves the latest 5 foo (unless it’s a Tuesday), but also removes the oldest foo, sends some random administrator a loosely related email, and might possible do a perfect frontflip and backflip to wrap things up (though not always, and we’ve yet to figure out why it doesn’t do the backflip before the frontflip).

 

Getting out of sync was the perfect term I was looking for. Thanks, Ben!

code of conduct - report abuse