I think it's really important with documentation (just like with any writing) that you are really clear with who your audience is.
Usually the only people that will see code comments are maintainers of the code, so I think anything that you would want to tell another maintainer that you would work with should be communicated in comments. This is a personal preference that I think is based on not always knowing who would work on my code after me. But if code is successful, hopefully somebody you don't know will try to extend it and not have to ask you questions about it directly.
Comments on public functions or methods are usually for users of the library, who probably don't want to look into the source code to find out what a function does. The function name might be descriptive, but what about the parameters it takes, or the side effects it might have? Strongly typed languages can help somewhat with this, but I think these important details should always be communicated somehow to the user in the documentation.
Users often don't ask questions about things they are confused about, they just move on to something easier to understand.
First of all, sorry for such a long silence, I've been meaning to answer for quite a long time now... But I wanted to do it right and properly.
@mohr023
My solution to the second problem was not ideal, I admit that. Your Answer still makes a wrong assumption. Let me explain what I mean, and my attempt at a better solution.
Your answer relies on the assumption that by proxying some method, you end up creating a culture of proxying. But if everyone actually writes clean code (which, since this is a thought experiment, we can assume) somebody will notice the chain of method proxying and refactor the necessary code to be clean again. Which would probably end up in my next proposed solution. You also mention that increased usability, or at least increased size of the interface is not helpful, or necessary. If this is the case, which it surely can be, I would still use proxying and simple call a private method in such a case. This still makes it instantly clear what the default method does (since the next method call explains it and is the only in the default method's body).
You make a very good point about the many options though. My previously suggested solution does not scale very well, that's true. For such a high-configurable Entity, I like to use the builder-pattern. Using the builder pattern you always start off using a default state, but can customize whatever necessary or desired. I would assume that in the case that event the builder pattern does not scale enough, I'd probably check whether I can somehow split the code further. Otherwise I'm out of ideas as well.
@eli
Bierman
Audience is key. That is totally true. I was mostly talking about in-project code, not code that would be used as a library. But if a library is very well written, I usually don't have to look at any documentation but can simply use autocompletion of my IDE to do what I want. Anything else will be faster via Google and StackOverflow or similar anyways, than reading the docs. At least for me. But specific project should have a full documentation either way. While programming languages should also be very intuitive in their naming, they do require docs with a full walk-through. Just to mention one relatively obvious example. There's always edge cases, and in German we have a saying: "Keine Regel ohne Ausnahme", which translates to "No rule without an exception" - which I find is really fitting for situations like this, and everywhere for that matter.
Partly in response to your (@eli
Bierman) answer, but also generally as well, I just want to mention that it is highly language dependent, whether and how much documentation is necessary. Some languages work on a higher level, which generally make them more readable for us humans to understand, while others work on a lower level. These languages generally need more docs, as even experienced developers might spend a few seconds figuring out what exactly a method does, even if the naming is ideal.
I actually write a lot of comments. But I also delete most of them. Very rarely does one stay in the code after I have worked on it and somebody has reviewed it. By explaining what a method does in a comment, which feels less restricted than a name, I can optimize the comment to derive a very good name for the method or whatever it is I am trying to name/commented on.
In the end it does come down to preference though. I myself like to rather look at the code and understand what it does than read docs, while for others it might be the other way around. Which is both valid. And if your target audience is bigger, I'd opt for documentation on public methods. Just so that everyone can be happy.
Exactly, I don't think we'll ever come to a single option that fits every case, but I guess that in the end, it's still valid to use comments only as a final resource, you know, not using them as an excuse to leave an ugly code behind.
As you mentioned about preference, I actually prefer when a library I'm using has in-built docs, so that I can quickly ctrl+space and confirm that the input, process and output are what I expected, but that doesn't mean I'm filled with joy when I see a "createDefaultDeployment" method and have to read it's docs piece by piece just to start going.
You make some very good points though, helped me consolidate a few thoughts on comment using and refactoring, thanks for taking your time going through them.
This is such an interesting conversation. When I was working primarily with Objective-C in Xcode, I was very comfortable using other code that didn't have any documentation, just a descriptive name like pushVideoFrameToBuffer, and I felt prepared to use it.
Now I usually work in dynamically-typed languages without an IDE, so that definitely biases me towards a small number of concisely named public methods, because it is easier to remember what to type (and for me, easier to read too). Usually those methods are configurable by passing in arguments, like the builder pattern you mentioned @jeyj0
. It's interesting that design patterns are more constant across languages than naming patterns...
My current primary language Elixir lets you read each public method's comment from the interpreter, so it feels comfortable to refer to documentation to answer my questions about a method's usage. If I come across a library in Elixir with minimal documentation and long descriptive method names, it feels uncomfortable to use and I will probably look for a different one. The total opposite of what I expected in Objective-C.
Our code has to be a chameleon and blend into the surroundings. :)
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I think it's really important with documentation (just like with any writing) that you are really clear with who your audience is.
Usually the only people that will see code comments are maintainers of the code, so I think anything that you would want to tell another maintainer that you would work with should be communicated in comments. This is a personal preference that I think is based on not always knowing who would work on my code after me. But if code is successful, hopefully somebody you don't know will try to extend it and not have to ask you questions about it directly.
Comments on public functions or methods are usually for users of the library, who probably don't want to look into the source code to find out what a function does. The function name might be descriptive, but what about the parameters it takes, or the side effects it might have? Strongly typed languages can help somewhat with this, but I think these important details should always be communicated somehow to the user in the documentation.
Users often don't ask questions about things they are confused about, they just move on to something easier to understand.
An example of a code commenting style I strive for can be found in Fossil SCM's implementation of its internal scripting language TH1. It starts with a brief overview of what the file contains. Each function has a comment that answers the question "why does this function exist?" Check out the comment on an internal Buffer type. Here's an example of a comment that you might see as redundant, but another maintainer might see it as saving one precious minute of their time trying to figure out the purpose of that code.
First of all, sorry for such a long silence, I've been meaning to answer for quite a long time now... But I wanted to do it right and properly.
@mohr023
My solution to the second problem was not ideal, I admit that. Your Answer still makes a wrong assumption. Let me explain what I mean, and my attempt at a better solution.
Your answer relies on the assumption that by proxying some method, you end up creating a culture of proxying. But if everyone actually writes clean code (which, since this is a thought experiment, we can assume) somebody will notice the chain of method proxying and refactor the necessary code to be clean again. Which would probably end up in my next proposed solution. You also mention that increased usability, or at least increased size of the interface is not helpful, or necessary. If this is the case, which it surely can be, I would still use proxying and simple call a private method in such a case. This still makes it instantly clear what the default method does (since the next method call explains it and is the only in the default method's body).
You make a very good point about the many options though. My previously suggested solution does not scale very well, that's true. For such a high-configurable Entity, I like to use the builder-pattern. Using the builder pattern you always start off using a default state, but can customize whatever necessary or desired. I would assume that in the case that event the builder pattern does not scale enough, I'd probably check whether I can somehow split the code further. Otherwise I'm out of ideas as well.
@eli Bierman
Audience is key. That is totally true. I was mostly talking about in-project code, not code that would be used as a library. But if a library is very well written, I usually don't have to look at any documentation but can simply use autocompletion of my IDE to do what I want. Anything else will be faster via Google and StackOverflow or similar anyways, than reading the docs. At least for me. But specific project should have a full documentation either way. While programming languages should also be very intuitive in their naming, they do require docs with a full walk-through. Just to mention one relatively obvious example. There's always edge cases, and in German we have a saying: "Keine Regel ohne Ausnahme", which translates to "No rule without an exception" - which I find is really fitting for situations like this, and everywhere for that matter.
Partly in response to your (@eli Bierman) answer, but also generally as well, I just want to mention that it is highly language dependent, whether and how much documentation is necessary. Some languages work on a higher level, which generally make them more readable for us humans to understand, while others work on a lower level. These languages generally need more docs, as even experienced developers might spend a few seconds figuring out what exactly a method does, even if the naming is ideal.
I actually write a lot of comments. But I also delete most of them. Very rarely does one stay in the code after I have worked on it and somebody has reviewed it. By explaining what a method does in a comment, which feels less restricted than a name, I can optimize the comment to derive a very good name for the method or whatever it is I am trying to name/commented on.
In the end it does come down to preference though. I myself like to rather look at the code and understand what it does than read docs, while for others it might be the other way around. Which is both valid. And if your target audience is bigger, I'd opt for documentation on public methods. Just so that everyone can be happy.
:)
Exactly, I don't think we'll ever come to a single option that fits every case, but I guess that in the end, it's still valid to use comments only as a final resource, you know, not using them as an excuse to leave an ugly code behind.
As you mentioned about preference, I actually prefer when a library I'm using has in-built docs, so that I can quickly ctrl+space and confirm that the input, process and output are what I expected, but that doesn't mean I'm filled with joy when I see a "createDefaultDeployment" method and have to read it's docs piece by piece just to start going.
You make some very good points though, helped me consolidate a few thoughts on comment using and refactoring, thanks for taking your time going through them.
This is such an interesting conversation. When I was working primarily with Objective-C in Xcode, I was very comfortable using other code that didn't have any documentation, just a descriptive name like
pushVideoFrameToBuffer, and I felt prepared to use it.Now I usually work in dynamically-typed languages without an IDE, so that definitely biases me towards a small number of concisely named public methods, because it is easier to remember what to type (and for me, easier to read too). Usually those methods are configurable by passing in arguments, like the builder pattern you mentioned @jeyj0 . It's interesting that design patterns are more constant across languages than naming patterns...
My current primary language Elixir lets you read each public method's comment from the interpreter, so it feels comfortable to refer to documentation to answer my questions about a method's usage. If I come across a library in Elixir with minimal documentation and long descriptive method names, it feels uncomfortable to use and I will probably look for a different one. The total opposite of what I expected in Objective-C.
Our code has to be a chameleon and blend into the surroundings. :)