Comment by WalterBright
2 years ago
Documentation exists in one of these states:
1. incomplete
2. wrong
3. missing
My goal is to write code that is so clear it doesn't need documentation.
2 years ago
Documentation exists in one of these states:
1. incomplete
2. wrong
3. missing
My goal is to write code that is so clear it doesn't need documentation.
Some functions are doing jobs well-defined enough that this is sufficient, but there's plenty that aren't and do deserve additional explanation.
I don't want to read the code of your function to figure out what its doing. I want to read the function signature, and if that's not clear enough a comment explaining its purpose and parameters. Code explains how it does something, but often does not clearly explain what that something is.
I don't expect to attain it, which is why I remarked on it as a goal. I've discovered that a lot can be done to eliminate the need for some forms of documentation. Also a lot can be done with the language to make it more expressive, and thus eliminating the need to document something.
For example, having the parameter to a function declared `const` means the function cannot alter it, and this is checked by the compiler. It won't be necessary to mention that in the function documentation.
P.S. This doesn't work in C and C++, despite them having a `const` type qualifier. This is because the `const` is not transitive, and can be legitimately cast away. Therefore, it's useless as a guarantee. D's `const` is transitive, and although you can cast it away in @system code, you're on your own with that.
> For example, having the parameter to a function declared `const` means the function cannot alter it, and this is checked by the compiler. It won't be necessary to mention that in the function documentation.
Actually you should mention it in the documentation. There's 2 types of documentation, so it's easier to just do the one: documentation for users, documentation for developers. Unless you work absolutely alone on all your projects and you don't open source them, someone else is going to be reading your code.
4 replies →
> 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.
2 replies →
Please at least document the 'why' of the code. Anyone can spend an eternity on a codebase and figure out 'what' it does, but its very difficult to figure out the 'why' without someone explicitly telling you.
In your opinion/experience, does (or: would) a docs-as-code approach help ?
Docs-as-code will never work, as human languages are way too mushy and imprecise. That's why we have programming languages.
I document as I code all the time. It is immensely helpful. As I write the signature I add a few lines saying what the function will do and often it results in me slightly modifying the function because I realize a better way.
I think you miss the point. Docs-as-code says keep the docs where the code is, and manage the docs like you manage code, using tools like git. Mostly(?) to reduce friction for software developers to actually contribute useful documentation.