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.
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.
Someone else is going to {read,edit,write,maintain} your code. Which means __anything__ the code does should be explained. Before you were suggesting documentation is only for the user. Documentation is also important for the developer. Whoever takes over your code later or works on it with you.
I think we're talking about different things then. I don't think you need to document every single line of code. That would be insane and is absurdly pedantic. No one is suggesting you (more than) double the amount of text in a codebase.
But you should write summarize your abstractions. So that's your classes and functions. I agree with the other commenter that what is of most concern is the method's signature. Also, a naming might be obvious, but I assure you it is not. What is obvious to some is not obvious to others. In addition to this, the code changes over time. What once might have been obvious no longer is later down the line. Expect this to happen because you want to handle failure in your "system" (in this case, the style in which you write code). The more complexity in a method, the more important it is to document.
If you need an example I think both the main article AND the comments here are quite enlightening[0]. In fact, I'd say the comments perfectly prove the author's point. The author writes very clearly how when playing the game you should operate under purely the letter of the law but top comment claims crystal clarity yet mentions "intent." A point explicitly mentioned that one should ignore by the author.
Just think of documentation as information entropy. By adding a few words you increase the information gain for someone who has never before looked at the code. I've also given you reasons as to why you are likely to also benefit, so if you need a purely selfish reason to document, this too exists. But we must differentiate long term utility vs short term to see the reasoning.
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.
As said in the other conversation, you're missing what's being communicated. And as __explicitly__ stated in the comment you replied to (this comment's gp), the compiler tells you __nothing__ about the logic. It can't! The compiler doesn't know human intention. It can tell you that you've accessed an out of bounds index, but it can't tell you that you selected the wrong index. These are very different things!
A compiler only tells you about semantic errors. It has no understanding though. This is true for any language. We can say/write things that are linguistically correct but have no actual meaning and tells us nothing about the "correctness" or efficiency of our usage.
Comments are for the logic, not grammar. The logic is abstract.
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.
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.
