Comment by godelski
2 years ago
> My goal is to write code that is so clear it doesn't need documentation.
I hear this so often but I think it is an excuse. Those 3 points are also true about your code.
> There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors
> Those 3 points are also true about your code.
The difference is there are things the compiler can verify to be correct.
This conversation is a bit difficult when you're ignoring a fair amount of what I and others have said. I think you're wanting to be right so interpreting the words to support that.
The compiler does not tell you that code is correct. It has no such capability and even LLMs are far away from doing that. The compiler can only tell you that the code is compilable. That means the syntax is correct, but it does not mean the logic is. The logic is much more abstract in terms of correctness.
The compiler can verify for you that a pointer to const does not modify the pointed to data. It is not necessary to document it.
There are a number of constructs in C that require documentation because they are not expressible in code. More expressivity in the language reduces the documentation required. An ownership/borrowing capability means one doesn't have to document who the "owner" is. And so on.
1 reply →