Well, that's kind of my point. What helps you go through the code in less time?

You can leave comments describing the "what" of the code. What a piece of code does, what's its purpose and/or the problem it solves. "This method should fetch X from Z when some conditions apply .in order to .... etc". That's valuable insofar that you can make it descriptive and brief (the attention span issue).

You can also comment describing the "how". To achieve the "what" I've implemented a recursive binary tree search which transforms Z in a tree and applies the conditions to fetch X. But if the next developer isn't familiar with binary search trees? Or the way you're phrasing things simply doesn't seem clear to them? When you move to beyond the "what" things tend to need more explanations. You're better off writing proper technical documentation in some knowledge repository than comments in code. But even then it boils down to a cost/benefit evaluation. In my experience people would first go to Stackoverflow to learn about the "how" than study any in-house documentation.


Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store