Code like you’re leaving tomorrow and everyone is stupid

The documentation dilema has existed since the very first lines of code. Even today, there still isn’t a proper solution for this problem.

Based on my experience in various companies and enterprises, I would like to introduce my way of keeping your stuff documented, which is a combination of a few good practices. “Code like you’re leaving tomorrow and everyone is stupid”, that is.

If you’re leaving tomorrow, how will the other devs understand what you’ve written?

• Endless confluence pages? not a solution.
• Documentation inside the code? good, but are you sure you’re going to maintain it with all the changes to come? I’m pretty sure you won’t.
• Video tutorials? Those get obsolete faster than an avarage JS framework.

No, all of those can’t work on their own. They will most likely be irrelevant on the next change you (or someone else) make to your codebase.

What I would suggest is combination of naming your methods in a certain way + comments\xml documentation inside the code. Let me show you:

Instead of “void InitializeModel”, try something like “void ReadDataFromStorageAndAddToModelMap”.

Instead of “FindMatch”, try “GetHighestModelByValue”.

If more explaining is needed — you might add on the side as a comment.

But think about it this way: If what your method does changes, the chances of changing its signature are very high, while the comments on the side will most likely be ignored. If you name your methods in a very specific way, explaining in its name exactly what the method does — you can be 95% sure that this is what the method does, and if something changes — the name will change as well.

Code like you’re leaving tomorrow and everyone is stupid. Works every time.