This does not apply to very simple functions where the function name can describe everything like removeLastCharacter(). But calculateSingularityProbability() might win by some description.
calculateSingularityProbability() is already a pretty good summary, isn't it? It shouldn't be necessary to describe formally what the function does exactly because, well, that's exactly what code is: a formal description of behavior.
If you write code that you think is hard to read and needs a comment then why don't you change the code instead of adding a comment? This is like creating a product with a crappy UX and then writing a descriptive manual instead of fixing the UX.
Why are you doing array.pop() twice here without any appearant reason? Well, because I do know that the array always contains two empty entries at the end, which we don't want.
Why don't you wrap the double array.pop() in a function named removeEmptyArraysAtTheEnd()? Shorter functions, single responsibility maintained and description inside the function title. No risk of "changing the function but forgetting to change the comment".
In my opinion, writing comments is the last resort and should almost never be done. Instead, keep functions very short (10 -30 LOC) and parameter count low. I recommend reading Uncle Bob's "Clean Code".
I am working as a web developer for nearly 20 years. I care a lot about simple and maintainable code that is fun to work with, good documentation and clean APIs.
I prefer reading one line of comment in human language than having to read 10 - 30 lines of machine language and parse it in my head to figure out whats going on.
Don't you prefer to read one function title that describes on a high level in human readable language what's inside the function? Basically the same that would be in the one comment line?
I am working as a web developer for nearly 20 years. I care a lot about simple and maintainable code that is fun to work with, good documentation and clean APIs.
We went full circle to my initial comment. Yes, there are simple function where all they do fits into the function name.
Since functions are composed from other functions no matter how much you break things up, you will end up with something more complex. And the case will be even worse since I now have to scan all over the place nd go down rabbit holes to understand whats going on inside.
I also mentioned that its depending on the cases. You cannot generalize the topic.
I understand what you're saying. I would argue, though, that only because you add a layer of abstraction to something, it doesn't mean that you need to understand every detail of the layer below to understand the abstraction. I would even say that's the purpose of abstraction.
So when you compose 5 functions in a new function, you don't need to read the code of the 5 child functions if they have a descriptive name.
If I wrap five HTTP requests in a repository, I don't need to understand the HTTP request logic to refactor the repository. I can stay in this layer of abstraction because I separated all the logic into smaller pieces.
I would argue that if a function does more than fits in the function name, the function does too much. If it's only one responsibility, it can be usually described in a short title.
But we may have made different experiences and we will possibly not come together and agree here and this is fine :).
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 have to say, I disagree.
calculateSingularityProbability()is already a pretty good summary, isn't it? It shouldn't be necessary to describe formally what the function does exactly because, well, that's exactly what code is: a formal description of behavior.If you write code that you think is hard to read and needs a comment then why don't you change the code instead of adding a comment? This is like creating a product with a crappy UX and then writing a descriptive manual instead of fixing the UX.
Why don't you wrap the double
array.pop()in a function namedremoveEmptyArraysAtTheEnd()? Shorter functions, single responsibility maintained and description inside the function title. No risk of "changing the function but forgetting to change the comment".In my opinion, writing comments is the last resort and should almost never be done. Instead, keep functions very short (10 -30 LOC) and parameter count low. I recommend reading Uncle Bob's "Clean Code".
I prefer reading one line of comment in human language than having to read 10 - 30 lines of machine language and parse it in my head to figure out whats going on.
I read that book. Also many others. 👍
Don't you prefer to read one function title that describes on a high level in human readable language what's inside the function? Basically the same that would be in the one comment line?
We went full circle to my initial comment. Yes, there are simple function where all they do fits into the function name.
Since functions are composed from other functions no matter how much you break things up, you will end up with something more complex. And the case will be even worse since I now have to scan all over the place nd go down rabbit holes to understand whats going on inside.
I also mentioned that its depending on the cases. You cannot generalize the topic.
I understand what you're saying. I would argue, though, that only because you add a layer of abstraction to something, it doesn't mean that you need to understand every detail of the layer below to understand the abstraction. I would even say that's the purpose of abstraction.
So when you compose 5 functions in a new function, you don't need to read the code of the 5 child functions if they have a descriptive name.
If I wrap five HTTP requests in a repository, I don't need to understand the HTTP request logic to refactor the repository. I can stay in this layer of abstraction because I separated all the logic into smaller pieces.
I would argue that if a function does more than fits in the function name, the function does too much. If it's only one responsibility, it can be usually described in a short title.
But we may have made different experiences and we will possibly not come together and agree here and this is fine :).