Comment by godelski
2 years ago
And people who comment their code. Even if it is just a little. I swear, 90% of my time in coding is just fiddling around with functions to see what they do so that I can actually pull them together in the right way. If there was just a little documentation this would greatly reduce my time. It should also be in every team's and company's best interest because people hours are expensive. It should also be in the best interest of an open source project because more people will be able to build on your stuff. It should also be in your own interest because taking the 30 seconds to a minute to write those lines interrupts you and allows you to rethink and verify your method. So not doing it is only in the interest of moving fast and writing spaghetti code. But you're not actually moving fast. You move fast at that moment, but not in the race.
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.
5 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.
3 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.
2 replies →