> “ Most things I can name easy enough, such as "Name" or "URL" or "MaxSizeN". The first 2 are self explanatory, the last one is the maximum size of something i

> “ Most things I can name easy enough, such as "Name" or "URL" or "MaxSizeN". The first 2 are self explanatory, the last one is the maximum size of something in relevant data units(as opposed to bytes or some other unit) but that one is easily understood by other programmers too.” Programmers who think like this frighten me a lot. Those parameter names are not self explanatory at all, and cannot be assumed readily understood by developers picking up the code. If you think “this is obvious” you need to add “to me” on the end, and “not necessarily to other people.” This can go off the rails when people start making braindead claims that code should be self-documenting and need for comments or docstrings indicates poor code. But it can also just lead to bad documentation where you think a word is clear enough and you don’t realize others will cone into that segment of code with totally different use cases or contexts in mind, assumptions about the code’s usage constraints, different levels of skill and experience, different levels of comfort with the natural language that comments are written in. Over-communicating within documentation is a hugely beneficial thing. It only costs a small amount of hassle for the person writing it and a small amount of hassle dealing with the eyesore of it for people already familiar, but it saves so much cognitive load for everyone else. The main downside is keeping it up to date, but the false adage that wrong documentation is worse than no documentation is no excuse.